From 25a767835262562dc9e8809c057f984d2812cb46 Mon Sep 17 00:00:00 2001 From: mike-m Date: Thu, 6 May 2010 23:46:27 +0000 Subject: 2nd part of: Overhauled llvm/clang docs builds. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@103214 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/AnalyzerRegions.html | 258 ----- docs/Block-ABI-Apple.txt | 670 ------------- docs/BlockLanguageSpec.txt | 165 ---- docs/DriverArchitecture.png | Bin 72966 -> 0 bytes docs/DriverInternals.html | 517 ---------- docs/InternalsManual.html | 1681 --------------------------------- docs/LanguageExtensions.html | 658 ------------- docs/Makefile | 88 +- docs/PCHInternals.html | 500 ---------- docs/PCHLayout.graffle | 1880 ------------------------------------- docs/PCHLayout.png | Bin 31908 -> 0 bytes docs/PTHInternals.html | 177 ---- docs/UsersManual.html | 904 ------------------ docs/api/Makefile | 25 + docs/api/api.css | 319 +++++++ docs/api/doxygen.cfg.in | 1553 ++++++++++++++++++++++++++++++ docs/api/footer.html | 14 + docs/api/header.html | 13 + docs/api/intro.h | 23 + docs/api/layout.xml | 184 ++++ docs/doxygen.cfg | 1230 ------------------------ docs/doxygen.cfg.in | 1230 ------------------------ docs/doxygen.css | 378 -------- docs/doxygen.footer | 10 - docs/doxygen.header | 9 - docs/doxygen.intro | 15 - docs/index.html | 4 - docs/libIndex.html | 267 ------ docs/main/AnalyzerRegions.html | 258 +++++ docs/main/Block-ABI-Apple.txt | 670 +++++++++++++ docs/main/BlockLanguageSpec.txt | 165 ++++ docs/main/DriverArchitecture.png | Bin 0 -> 72966 bytes docs/main/DriverInternals.html | 517 ++++++++++ docs/main/InternalsManual.html | 1681 +++++++++++++++++++++++++++++++++ docs/main/LanguageExtensions.html | 658 +++++++++++++ docs/main/Makefile | 18 + docs/main/PCHInternals.html | 500 ++++++++++ docs/main/PCHLayout.graffle | 1880 +++++++++++++++++++++++++++++++++++++ docs/main/PCHLayout.png | Bin 0 -> 31908 bytes docs/main/PTHInternals.html | 177 ++++ docs/main/UsersManual.html | 904 ++++++++++++++++++ docs/main/index.html | 4 + docs/main/libIndex.html | 267 ++++++ docs/main/tools/clang.pod | 518 ++++++++++ docs/main/tools/manpage.css | 256 +++++ docs/tools/Makefile | 115 --- 46 files changed, 10606 insertions(+), 10754 deletions(-) delete mode 100644 docs/AnalyzerRegions.html delete mode 100644 docs/Block-ABI-Apple.txt delete mode 100644 docs/BlockLanguageSpec.txt delete mode 100644 docs/DriverArchitecture.png delete mode 100644 docs/DriverInternals.html delete mode 100644 docs/InternalsManual.html delete mode 100644 docs/LanguageExtensions.html delete mode 100644 docs/PCHInternals.html delete mode 100644 docs/PCHLayout.graffle delete mode 100644 docs/PCHLayout.png delete mode 100644 docs/PTHInternals.html delete mode 100644 docs/UsersManual.html create mode 100644 docs/api/Makefile create mode 100644 docs/api/api.css create mode 100644 docs/api/doxygen.cfg.in create mode 100644 docs/api/footer.html create mode 100644 docs/api/header.html create mode 100644 docs/api/intro.h create mode 100644 docs/api/layout.xml delete mode 100644 docs/doxygen.cfg delete mode 100644 docs/doxygen.cfg.in delete mode 100644 docs/doxygen.css delete mode 100644 docs/doxygen.footer delete mode 100644 docs/doxygen.header delete mode 100644 docs/doxygen.intro delete mode 100644 docs/index.html delete mode 100644 docs/libIndex.html create mode 100644 docs/main/AnalyzerRegions.html create mode 100644 docs/main/Block-ABI-Apple.txt create mode 100644 docs/main/BlockLanguageSpec.txt create mode 100644 docs/main/DriverArchitecture.png create mode 100644 docs/main/DriverInternals.html create mode 100644 docs/main/InternalsManual.html create mode 100644 docs/main/LanguageExtensions.html create mode 100644 docs/main/Makefile create mode 100644 docs/main/PCHInternals.html create mode 100644 docs/main/PCHLayout.graffle create mode 100644 docs/main/PCHLayout.png create mode 100644 docs/main/PTHInternals.html create mode 100644 docs/main/UsersManual.html create mode 100644 docs/main/index.html create mode 100644 docs/main/libIndex.html create mode 100644 docs/main/tools/clang.pod create mode 100644 docs/main/tools/manpage.css delete mode 100644 docs/tools/Makefile (limited to 'docs') diff --git a/docs/AnalyzerRegions.html b/docs/AnalyzerRegions.html deleted file mode 100644 index 35708d57c9..0000000000 --- a/docs/AnalyzerRegions.html +++ /dev/null @@ -1,258 +0,0 @@ - - -Static Analyzer Design Document: Memory Regions - - - -

Static Analyzer Design Document: Memory Regions

- -

Authors

- -

Ted Kremenek, kremenek at apple
-Zhongxing Xu, xuzhongzhing at gmail

- -

Introduction

- -

The path-sensitive analysis engine in libAnalysis employs an extensible API -for abstractly modeling the memory of an analyzed program. This API employs the -concept of "memory regions" to abstractly model chunks of program memory such as -program variables and dynamically allocated memory such as those returned from -'malloc' and 'alloca'. Regions are hierarchical, with subregions modeling -subtyping relationships, field and array offsets into larger chunks of memory, -and so on.

- -

The region API consists of two components:

- - - -

Symbolic stores, which can be thought of as representing the relation -regions -> values, are implemented by subclasses of the -StoreManager class (Store.h). A -particular StoreManager implementation has complete flexibility concerning the -following: - -

- -

Together, both points allow different StoreManagers to tradeoff between -different levels of analysis precision and scalability concerning the reasoning -of program memory. Meanwhile, the core path-sensitive engine makes no -assumptions about either points, and queries a StoreManager about the bindings -to a memory region through a generic interface that all StoreManagers share. If -a particular StoreManager cannot reason about the potential bindings of a given -memory region (e.g., 'BasicStoreManager' does not reason about fields -of structures) then the StoreManager can simply return 'unknown' (represented by -'UnknownVal') for a particular region-binding. This separation of -concerns not only isolates the core analysis engine from the details of -reasoning about program memory but also facilities the option of a client of the -path-sensitive engine to easily swap in different StoreManager implementations -that internally reason about program memory in very different ways. - -

The rest of this document is divided into two parts. We first discuss region -taxonomy and the semantics of regions. We then discuss the StoreManager -interface, and details of how the currently available StoreManager classes -implement region bindings.

- -

Memory Regions and Region Taxonomy

- -

Pointers

- -

Before talking about the memory regions, we would talk about the pointers -since memory regions are essentially used to represent pointer values.

- -

The pointer is a type of values. Pointer values have two semantic aspects. -One is its physical value, which is an address or location. The other is the -type of the memory object residing in the address.

- -

Memory regions are designed to abstract these two properties of the pointer. -The physical value of a pointer is represented by MemRegion pointers. The rvalue -type of the region corresponds to the type of the pointee object.

- -

One complication is that we could have different view regions on the same -memory chunk. They represent the same memory location, but have different -abstract location, i.e., MemRegion pointers. Thus we need to canonicalize the -abstract locations to get a unique abstract location for one physical -location.

- -

Furthermore, these different view regions may or may not represent memory -objects of different types. Some different types are semantically the same, -for example, 'struct s' and 'my_type' are the same type.

- -
-struct s;
-typedef struct s my_type;
-
- -

But char and int are not the same type in the code below:

- -
-void *p;
-int *q = (int*) p;
-char *r = (char*) p;
-
Thus we need to canonicalize the MemRegion which is used in binding and -retrieving.

- -

Regions

-

Region is the entity used to model pointer values. A Region has the following -properties:

- - - -

Symbolic Regions

- -

A symbolic region is a map of the concept of symbolic values into the domain -of regions. It is the way that we represent symbolic pointers. Whenever a -symbolic pointer value is needed, a symbolic region is created to represent -it.

- -

A symbolic region has no type. It wraps a SymbolData. But sometimes we have -type information associated with a symbolic region. For this case, a -TypedViewRegion is created to layer the type information on top of the symbolic -region. The reason we do not carry type information with the symbolic region is -that the symbolic regions can have no type. To be consistent, we don't let them -to carry type information.

- -

Like a symbolic pointer, a symbolic region may be NULL, has unknown extent, -and represents a generic chunk of memory.

- -

NOTE: We plan not to use loc::SymbolVal in RegionStore and remove it - gradually.

- -

Symbolic regions get their rvalue types through the following ways:

- - - -

We attach the type information to the symbolic region lazily. For the first -case above, we create the TypedViewRegion only when the pointer is -actually used to access the pointee memory object, that is when the element or -field region is created. For the cast case, the TypedViewRegion is -created when visiting the CastExpr.

- -

The reason for doing lazy typing is that symbolic regions are sometimes only -used to do location comparison.

- -

Pointer Casts

- -

Pointer casts allow people to impose different 'views' onto a chunk of -memory.

- -

Usually we have two kinds of casts. One kind of casts cast down with in the -type hierarchy. It imposes more specific views onto more generic memory regions. -The other kind of casts cast up with in the type hierarchy. It strips away more -specific views on top of the more generic memory regions.

- -

We simulate the down casts by layering another TypedViewRegion on -top of the original region. We simulate the up casts by striping away the top -TypedViewRegion. Down casts is usually simple. For up casts, if the -there is no TypedViewRegion to be stripped, we return the original -region. If the underlying region is of the different type than the cast-to type, -we flag an error state.

- -

For toll-free bridging casts, we return the original region.

- -

We can set up a partial order for pointer types, with the most general type -void* at the top. The partial order forms a tree with void* as -its root node.

- -

Every MemRegion has a root position in the type tree. For example, -the pointee region of void *p has its root position at the root node of -the tree. VarRegion of int x has its root position at the 'int -type' node.

- -

TypedViewRegion is used to move the region down or up in the tree. -Moving down in the tree adds a TypedViewRegion. Moving up in the tree -removes a TypedViewRegion.

- -

Do we want to allow moving up beyond the root position? This happens -when:

 int x; void *p = &x;
- -

The region of x has its root position at 'int*' node. the cast to -void* moves that region up to the 'void*' node. I propose to not allow such -casts, and assign the region of x for p.

- -

Another non-ideal case is that people might cast to a non-generic pointer -from another non-generic pointer instead of first casting it back to the generic -pointer. Direct handling of this case would result in multiple layers of -TypedViewRegions. This enforces an incorrect semantic view to the region, -because we can only have one typed view on a region at a time. To avoid this -inconsistency, before casting the region, we strip the TypedViewRegion, then do -the cast. In summary, we only allow one layer of TypedViewRegion.

- -

Region Bindings

- -

The following region kinds are boundable: VarRegion, CompoundLiteralRegion, -StringRegion, ElementRegion, FieldRegion, and ObjCIvarRegion.

- -

When binding regions, we perform canonicalization on element regions and field -regions. This is because we can have different views on the same region, some -of which are essentially the same view with different sugar type names.

- -

To canonicalize a region, we get the canonical types for all TypedViewRegions -along the way up to the root region, and make new TypedViewRegions with those -canonical types.

- -

For Objective-C and C++, perhaps another canonicalization rule should be -added: for FieldRegion, the least derived class that has the field is used as -the type of the super region of the FieldRegion.

- -

All bindings and retrievings are done on the canonicalized regions.

- -

Canonicalization is transparent outside the region store manager, and more -specifically, unaware outside the Bind() and Retrieve() method. We don't need to -consider region canonicalization when doing pointer cast.

- -

Constraint Manager

- -

The constraint manager reasons about the abstract location of memory objects. -We can have different views on a region, but none of these views changes the -location of that object. Thus we should get the same abstract location for those -regions.

- - - diff --git a/docs/Block-ABI-Apple.txt b/docs/Block-ABI-Apple.txt deleted file mode 100644 index dd12036053..0000000000 --- a/docs/Block-ABI-Apple.txt +++ /dev/null @@ -1,670 +0,0 @@ -Block Implementation Specification - -Copyright 2008-2010 Apple, Inc. -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - -0. History - -2008/7/14 - created -2008/8/21 - revised, C++ -2008/9/24 - add NULL isa field to __block storage -2008/10/1 - revise block layout to use a static descriptor structure -2008/10/6 - revise block layout to use an unsigned long int flags -2008/10/28 - specify use of _Block_object_assign/dispose for all "Object" types in helper functions -2008/10/30 - revise new layout to have invoke function in same place -2008/10/30 - add __weak support - -2010/3/16 - rev for stret return, signature field -2010/4/6 - improved wording - -This document describes the Apple ABI implementation specification of Blocks. - -The first shipping version of this ABI is found in Mac OS X 10.6, and shall be referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI contract with the runtime and the compiler, and, as necessary, will be referred to as ABI.2010.3.16. - -Since the Apple ABI references symbols from other elements of the system, any attempt to use this ABI on systems prior to SnowLeopard is undefined. - -1. High Level - -The ABI of blocks consist of their layout and the runtime functions required by the compiler. -A Block consists of a structure of the following form: - -struct Block_literal_1 { - void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock - int flags; - int reserved; - void (*invoke)(void *, ...); - struct Block_descriptor_1 { - unsigned long int reserved; // NULL - unsigned long int size; // sizeof(struct Block_literal_1) - // optional helper functions - void (*copy_helper)(void *dst, void *src); // IFF (1<<25) - void (*dispose_helper)(void *src); // IFF (1<<25) - // required ABI.2010.3.16 - const char *signature; // IFF (1<<30) - } *descriptor; - // imported variables -}; - -The following flags bits are in use thusly for a possible ABI.2010.3.16: - -enum { - BLOCK_HAS_COPY_DISPOSE = (1 << 25), - BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code - BLOCK_IS_GLOBAL = (1 << 28), - BLOCK_HAS_STRET = (1 << 29), - BLOCK_HAS_SIGNATURE = (1 << 30), -}; - -In 10.6.ABI the (1<<29) was unconditionally set and ignored by the runtime - it was a transitional marker that did not get deleted after the transition. This bit is now paired with (1<<30), and represented as the pair (3<<30), for the following combinations of valid bit settings, and their meanings. - -switch (flags & (3<<29)) { - case (0<<29): , error - case (1<<29): 10.6.ABI, no signature field available - case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field - case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field, -} - -The following discussions are presented as 10.6.ABI otherwise. - -Block literals may occur within functions where the structure is created in stack local memory. They may also appear as initialization expressions for Block variables of global or static local variables. - -When a Block literal expression is evaluated the stack based structure is initialized as follows: - -1) static descriptor structure is declared and initialized as follows: -1a) the invoke function pointer is set to a function that takes the Block structure as its first argument and the rest of the arguments (if any) to the Block and executes the Block compound statement. -1b) the size field is set to the size of the following Block literal structure. -1c) the copy_helper and dispose_helper function pointers are set to respective helper functions if they are required by the Block literal -2) a stack (or global) Block literal data structure is created and initialized as follows: -2a) the isa field is set to the address of the external _NSConcreteStackBlock, which is a block of uninitialized memory supplied in libSystem, or _NSConcreteGlobalBlock if this is a static or file level block literal. -2) The flags field is set to zero unless there are variables imported into the block that need helper functions for program level Block_copy() and Block_release() operations, in which case the (1<<25) flags bit is set. - - -As an example, the Block literal expression - ^ { printf("hello world\n"); } -would cause to be created on a 32-bit system: - -struct __block_literal_1 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_1 *); - struct __block_descriptor_1 *descriptor; -}; - -void __block_invoke_1(struct __block_literal_1 *_block) { - printf("hello world\n"); -} - -static struct __block_descriptor_1 { - unsigned long int reserved; - unsigned long int Block_size; -} __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 }; - -and where the block literal appeared - - struct __block_literal_1 _block_literal = { - &_NSConcreteStackBlock, - (1<<29), , - __block_invoke_1, - &__block_descriptor_1 - }; - -Blocks import other Block references, const copies of other variables, and variables marked __block. In Objective-C variables may additionally be objects. - -When a Block literal expression used as the initial value of a global or static local variable it is initialized as follows: - struct __block_literal_1 __block_literal_1 = { - &_NSConcreteGlobalBlock, - (1<<28)|(1<<29), , - __block_invoke_1, - &__block_descriptor_1 - }; -that is, a different address is provided as the first value and a particular (1<<28) bit is set in the flags field, and otherwise it is the same as for stack based Block literals. This is an optimization that can be used for any Block literal that imports no const or __block storage variables. - - -2. Imported Variables - -Variables of "auto" storage class are imported as const copies. Variables of "__block" storage class are imported as a pointer to an enclosing data structure. Global variables are simply referenced and not considered as imported. - -2.1 Imported const copy variables - -Automatic storage variables not marked with __block are imported as const copies. - -The simplest example is that of importing a variable of type int. - - int x = 10; - void (^vv)(void) = ^{ printf("x is %d\n", x); } - x = 11; - vv(); - -would be compiled - -struct __block_literal_2 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_2 *); - struct __block_descriptor_2 *descriptor; - const int x; -}; - -void __block_invoke_2(struct __block_literal_2 *_block) { - printf("x is %d\n", _block->x); -} - -static struct __block_descriptor_2 { - unsigned long int reserved; - unsigned long int Block_size; -} __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) }; - -and - - struct __block_literal_2 __block_literal_2 = { - &_NSConcreteStackBlock, - (1<<29), , - __block_invoke_2, - &__block_descriptor_2, - x - }; - -In summary, scalars, structures, unions, and function pointers are generally imported as const copies with no need for helper functions. - -2.2 Imported const copy of Block reference - -The first case where copy and dispose helper functions are required is for the case of when a block itself is imported. In this case both a copy_helper function and a dispose_helper function are needed. The copy_helper function is passed both the existing stack based pointer and the pointer to the new heap version and should call back into the runtime to actually do the copy operation on the imported fields within the block. The runtime functions are all described in Section 5.0 Runtime Helper Functions. - -An example: - - void (^existingBlock)(void) = ...; - void (^vv)(void) = ^{ existingBlock(); } - vv(); - -struct __block_literal_3 { - ...; // existing block -}; - -struct __block_literal_4 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_4 *); - struct __block_literal_3 *const existingBlock; -}; - -void __block_invoke_4(struct __block_literal_2 *_block) { - __block->existingBlock->invoke(__block->existingBlock); -} - -void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) { - //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0); - _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK); -} - -void __block_dispose_4(struct __block_literal_4 *src) { - // was _Block_destroy - _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK); -} - -static struct __block_descriptor_4 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src); - void (*dispose_helper)(struct __block_literal_4 *); -} __block_descriptor_4 = { - 0, - sizeof(struct __block_literal_4), - __block_copy_4, - __block_dispose_4, -}; - -and where it is used - - struct __block_literal_4 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<29), - __block_invoke_4, - & __block_descriptor_4 - existingBlock, - }; - -2.2.1 Importing __attribute__((NSObject)) variables. - -GCC introduces __attribute__((NSObject)) on structure pointers to mean "this is an object". This is useful because many low level data structures are declared as opaque structure pointers, e.g. CFStringRef, CFArrayRef, etc. When used from C, however, these are still really objects and are the second case where that requires copy and dispose helper functions to be generated. The copy helper functions generated by the compiler should use the _Block_object_assign runtime helper function and in the dispose helper the _Block_object_dispose runtime helper function should be called. - -For example, block xyzzy in the following - - struct Opaque *__attribute__((NSObject)) objectPointer = ...; - ... - void (^xyzzy)(void) = ^{ CFPrint(objectPointer); }; - -would have helper functions - -void __block_copy_xyzzy(struct __block_literal_5 *dst, struct __block_literal_5 *src) { - _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT); -} - -void __block_dispose_xyzzy(struct __block_literal_5 *src) { - _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT); -} - -generated. - - -2.3 Imported __block marked variables. - -2.3.1 Layout of __block marked variables - -The compiler must embed variables that are marked __block in a specialized structure of the form: - -struct _block_byref_xxxx { - void *isa; - struct Block_byref *forwarding; - int flags; //refcount; - int size; - typeof(marked_variable) marked_variable; -}; - -Variables of certain types require helper functions for when Block_copy() and Block_release() are performed upon a referencing Block. At the "C" level only variables that are of type Block or ones that have __attribute__((NSObject)) marked require helper functions. In Objective-C objects require helper functions and in C++ stack based objects require helper functions. Variables that require helper functions use the form: - -struct _block_byref_xxxx { - void *isa; - struct _block_byref_xxxx *forwarding; - int flags; //refcount; - int size; - // helper functions called via Block_copy() and Block_release() - void (*byref_keep)(void *dst, void *src); - void (*byref_dispose)(void *); - typeof(marked_variable) marked_variable; -}; - -The structure is initialized such that - a) the forwarding pointer is set to the beginning of its enclosing structure, - b) the size field is initialized to the total size of the enclosing structure, - c) the flags field is set to either 0 if no helper functions are needed or (1<<25) if they are, - d) the helper functions are initialized (if present) - e) the variable itself is set to its initial value. - f) the isa field is set to NULL - -2.3.2 Access to __block variables from within its lexical scope. - -In order to "move" the variable to the heap upon a copy_helper operation the compiler must rewrite access to such a variable to be indirect through the structures forwarding pointer. For example: - - int __block i = 10; - i = 11; - -would be rewritten to be: - - struct _block_byref_i { - void *isa; - struct _block_byref_i *forwarding; - int flags; //refcount; - int size; - int captured_i; - } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 11 }; - - i.forwarding->captured_i = 11; - -In the case of a Block reference variable being marked __block the helper code generated must use the _Block_object_assign and _Block_object_dispose routines supplied by the runtime to make the copies. For example: - - __block void (voidBlock)(void) = blockA; - voidBlock = blockB; - -would translate into - -struct _block_byref_voidBlock { - void *isa; - struct _block_byref_voidBlock *forwarding; - int flags; //refcount; - int size; - void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src); - void (*byref_dispose)(struct _block_byref_voidBlock *); - void (^captured_voidBlock)(void); -}; - -void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { - //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0); - _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); -} - -void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) { - //_Block_destroy(param->captured_voidBlock, 0); - _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)} - -and - struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *), - .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper, - .captured_voidBlock=blockA }; - - voidBlock.forwarding->captured_voidBlock = blockB; - - -2.3.3 Importing __block variables into Blocks - -A Block that uses a __block variable in its compound statement body must import the variable and emit copy_helper and dispose_helper helper functions that, in turn, call back into the runtime to actually copy or release the byref data block using the functions _Block_object_assign and _Block_object_dispose. - -For example: - - int __block i = 2; - functioncall(^{ i = 10; }); - -would translate to - -struct _block_byref_i { - void *isa; // set to NULL - struct _block_byref_voidBlock *forwarding; - int flags; //refcount; - int size; - void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); - void (*byref_dispose)(struct _block_byref_i *); - int captured_i; -}; - - -struct __block_literal_5 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_5 *); - struct __block_descriptor_5 *descriptor; - struct _block_byref_i *i_holder; -}; - -void __block_invoke_5(struct __block_literal_5 *_block) { - _block->forwarding->captured_i = 10; -} - -void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { - //_Block_byref_assign_copy(&dst->captured_i, src->captured_i); - _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); -} - -void __block_dispose_5(struct __block_literal_5 *src) { - //_Block_byref_release(src->captured_i); - _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); -} - -static struct __block_descriptor_5 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); - void (*dispose_helper)(struct __block_literal_5 *); -} __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 }; - -and - - struct _block_byref_i i = {( .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i) )}; - struct __block_literal_5 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<29), , - __block_invoke_5, - &__block_descriptor_5, - 2, - }; - -2.3.4 Importing __attribute__((NSObject)) __block variables - -A __block variable that is also marked __attribute__((NSObject)) should have byref_keep and byref_dispose helper functions that use _Block_object_assign and _Block_object_dispose. - -2.3.5 __block escapes - -Because Blocks referencing __block variables may have Block_copy() performed upon them the underlying storage for the variables may move to the heap. In Objective-C Garbage Collection Only compilation environments the heap used is the garbage collected one and no further action is required. Otherwise the compiler must issue a call to potentially release any heap storage for __block variables at all escapes or terminations of their scope. - - -2.3.6 Nesting - -Blocks may contain Block literal expressions. Any variables used within inner blocks are imported into all enclosing Block scopes even if the variables are not used. This includes const imports as well as __block variables. - -3. Objective C Extensions to Blocks - -3.1 Importing Objects - -Objects should be treated as __attribute__((NSObject)) variables; all copy_helper, dispose_helper, byref_keep, and byref_dispose helper functions should use _Block_object_assign and _Block_object_dispose. There should be no code generated that uses -retain or -release methods. - - -3.2 Blocks as Objects - -The compiler will treat Blocks as objects when synthesizing property setters and getters, will characterize them as objects when generating garbage collection strong and weak layout information in the same manner as objects, and will issue strong and weak write-barrier assignments in the same manner as objects. - -3.3 __weak __block Support - -Objective-C (and Objective-C++) support the __weak attribute on __block variables. Under normal circumstances the compiler uses the Objective-C runtime helper support functions objc_assign_weak and objc_read_weak. Both should continue to be used for all reads and writes of __weak __block variables: - objc_read_weak(&block->byref_i->forwarding->i) - -The __weak variable is stored in a _block_byref_xxxx structure and the Block has copy and dispose helpers for this structure that call: - _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); -and - _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); - - -In turn, the block_byref copy support helpers distinguish between whether the __block variable is a Block or not and should either call: - _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER); -for something declared as an object or - _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); -for something declared as a Block. - -A full example follows: - - - __block __weak id obj = ; - functioncall(^{ [obj somemessage]; }); - -would translate to - -struct _block_byref_obj { - void *isa; // uninitialized - struct _block_byref_obj *forwarding; - int flags; //refcount; - int size; - void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); - void (*byref_dispose)(struct _block_byref_i *); - int captured_obj; -}; - -void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { - //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0); - _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); -} - -void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) { - //_Block_destroy(param->captured_obj, 0); - _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); -}; - -for the block byref part and - -struct __block_literal_5 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_5 *); - struct __block_descriptor_5 *descriptor; - struct _block_byref_obj *byref_obj; -}; - -void __block_invoke_5(struct __block_literal_5 *_block) { - [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage]; -} - -void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { - //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj); - _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); -} - -void __block_dispose_5(struct __block_literal_5 *src) { - //_Block_byref_release(src->byref_obj); - _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); -} - -static struct __block_descriptor_5 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); - void (*dispose_helper)(struct __block_literal_5 *); -} __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 }; - -and within the compound statement: - - struct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj), - .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose, - .captured_obj = )}; - - struct __block_literal_5 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<29), , - __block_invoke_5, - &__block_descriptor_5, - &obj, // a reference to the on-stack structure containing "captured_obj" - }; - - - functioncall(_block_literal->invoke(&_block_literal)); - - -4.0 C++ Support - -Within a block stack based C++ objects are copied as const copies using the const copy constructor. It is an error if a stack based C++ object is used within a block if it does not have a const copy constructor. In addition both copy and destroy helper routines must be synthesized for the block to support the Block_copy() operation, and the flags work marked with the (1<<26) bit in addition to the (1<<25) bit. The copy helper should call the constructor using appropriate offsets of the variable within the supplied stack based block source and heap based destination for all const constructed copies, and similarly should call the destructor in the destroy routine. - -As an example, suppose a C++ class FOO existed with a const copy constructor. Within a code block a stack version of a FOO object is declared and used within a Block literal expression: - -{ - FOO foo; - void (^block)(void) = ^{ printf("%d\n", foo.value()); }; -} - -The compiler would synthesize - -struct __block_literal_10 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_10 *); - struct __block_descriptor_10 *descriptor; - const FOO foo; -}; - -void __block_invoke_10(struct __block_literal_10 *_block) { - printf("%d\n", _block->foo.value()); -} - -void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) { - comp_ctor(&dst->foo, &src->foo); -} - -void __block_dispose_10(struct __block_literal_10 *src) { - comp_dtor(&src->foo); -} - -static struct __block_descriptor_10 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src); - void (*dispose_helper)(struct __block_literal_10 *); -} __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 }; - -and the code would be: -{ - FOO foo; - comp_ctor(&foo); // default constructor - struct __block_literal_10 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<26)|(1<<29), , - __block_invoke_10, - &__block_descriptor_10, - }; - comp_ctor(&_block_literal->foo, &foo); // const copy into stack version - struct __block_literal_10 &block = &_block_literal; // assign literal to block variable - block->invoke(block); // invoke block - comp_dtor(&_block_literal->foo); // destroy stack version of const block copy - comp_dtor(&foo); // destroy original version -} - - -C++ objects stored in __block storage start out on the stack in a block_byref data structure as do other variables. Such objects (if not const objects) must support a regular copy constructor. The block_byref data structure will have copy and destroy helper routines synthesized by the compiler. The copy helper will have code created to perform the copy constructor based on the initial stack block_byref data structure, and will also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper will have code to do the destructor on the object stored within the supplied block_byref heap data structure. - -To support member variable and function access the compiler will synthesize a const pointer to a block version of the this pointer. - -5.0 Runtime Helper Functions - -The runtime helper functions are described in /usr/local/include/Block_private.h. To summarize their use, a block requires copy/dispose helpers if it imports any block variables, __block storage variables, __attribute__((NSObject)) variables, or C++ const copied objects with constructor/destructors. The (1<<26) bit is set and functions are generated. - -The block copy helper function should, for each of the variables of the type mentioned above, call - _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_); -in the copy helper and - _Block_object_dispose(->target, BLOCK_FIELD_); -in the dispose helper where - is - -enum { - BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ... - BLOCK_FIELD_IS_BLOCK = 7, // a block variable - BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable - - BLOCK_FIELD_IS_WEAK = 16, // declared __weak - - BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers -}; - -and of course the CTORs/DTORs for const copied C++ objects. - -The block_byref data structure similarly requires copy/dispose helpers for block variables, __attribute__((NSObject)) variables, or C++ const copied objects with constructor/destructors, and again the (1<<26) bit is set and functions are generated in the same manner. - -Under ObjC we allow __weak as an attribute on __block variables, and this causes the addition of BLOCK_FIELD_IS_WEAK orred onto the BLOCK_FIELD_IS_BYREF flag when copying the block_byref structure in the block copy helper, and onto the BLOCK_FIELD_ field within the block_byref copy/dispose helper calls. - -The prototypes, and summary, of the helper functions are - -/* Certain field types require runtime assistance when being copied to the heap. The following function is used - to copy fields of types: blocks, pointers to byref structures, and objects (including __attribute__((NSObject)) pointers. - BLOCK_FIELD_IS_WEAK is orthogonal to the other choices which are mutually exclusive. - Only in a Block copy helper will one see BLOCK_FIELD_IS_BYREF. - */ -void _Block_object_assign(void *destAddr, const void *object, const int flags); - -/* Similarly a compiler generated dispose helper needs to call back for each field of the byref data structure. - (Currently the implementation only packs one field into the byref structure but in principle there could be more). - The same flags used in the copy helper should be used for each call generated to this function: - */ -void _Block_object_dispose(const void *object, const int flags); - -The following functions have been used and will continue to be supported until new compiler support is complete. - -// Obsolete functions. -// Copy helper callback for copying a block imported into a Block -// Called by copy_helper helper functions synthesized by the compiler. -// The address in the destination block of an imported Block is provided as the first argument -// and the value of the existing imported Block is the second. -// Use: _Block_object_assign(dest, src, BLOCK_FIELD_IS_BLOCK {| BLOCK_FIELD_IS_WEAK}); -void _Block_copy_assign(struct Block_basic **dest, const struct Block_basic *src, const int flags); - -// Destroy helper callback for releasing Blocks imported into a Block -// Called by dispose_helper helper functions synthesized by the compiler. -// The value of the imported Block variable is passed back. -// Use: _Block_object_dispose(src, BLOCK_FIELD_IS_BLOCK {| BLOCK_FIELD_IS_WEAK}); -void _Block_destroy(const struct Block_basic *src, const int flags); - -// Byref data block copy helper callback -// Called by block copy helpers when copying __block structures -// Use: _Block_object_assign(dest, src, BLOCK_FIELD_IS_BYREF {| BLOCK_FIELD_IS_WEAK}); -void _Block_byref_assign_copy(struct Block_byref **destp, struct Block_byref *src); - -// Byref data block release helper callback -// Called by block release helpers when releasing a Block -// Called at escape points in scope where __block variables live (under non-GC-only conditions) -// Use: _Block_object_dispose(src, BLOCK_FIELD_IS_BYREF {| BLOCK_FIELD_IS_WEAK}); -void §(struct Block_byref *shared_struct); - - diff --git a/docs/BlockLanguageSpec.txt b/docs/BlockLanguageSpec.txt deleted file mode 100644 index a612fd2889..0000000000 --- a/docs/BlockLanguageSpec.txt +++ /dev/null @@ -1,165 +0,0 @@ -Language Specification for Blocks - -2008/2/25 — created -2008/7/28 — revised, __block syntax -2008/8/13 — revised, Block globals -2008/8/21 — revised, C++ elaboration -2008/11/1 — revised, __weak support -2009/1/12 — revised, explicit return types -2009/2/10 — revised, __block objects need retain - -Copyright 2008-2009 Apple, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -The Block Type - -A new derived type is introduced to C and, by extension, Objective-C, C++, and Objective-C++. Like function types, the Block type is a pair consisting of a result value type and a list of parameter types very similar to a function type. Blocks are intended to be used much like functions with the key distinction being that in addition to executable code they also contain various variable bindings to automatic (stack) or managed (heap) memory. - -The abstract declarator int (^)(char, float) describes a reference to a Block that, when invoked, takes two parameters, the first of type char and the second of type float, and returns a value of type int. The Block referenced is of opaque data that may reside in automatic (stack) memory, global memory, or heap memory. - - -Block Variable Declarations - -A variable with Block type is declared using function pointer style notation substituting ^ for *. The following are valid Block variable declarations: - void (^blockReturningVoidWithVoidArgument)(void); - int (^blockReturningIntWithIntAndCharArguments)(int, char); - void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int); - -Variadic ... arguments are supported. [variadic.c] A Block that takes no arguments must specify void in the argument list [voidarg.c]. An empty parameter list does not represent, as K&R provide, an unspecified argument list. Note: both gcc and clang support K&R style as a convenience. - -A Block reference may be cast to a pointer of arbitrary type and vice versa. [cast.c] A Block reference may not be dereferenced via the pointer dereference operator *, and thus a Block's size may not be computed at compile time. [sizeof.c] - - -Block Literal Expressions - -A Block literal expression produces a reference to a Block. It is introduced by the use of the ^ token as a unary operator. - Block_literal_expression ::= ^ block_decl compound_statement_body - block_decl ::= - block_decl ::= parameter_list - block_decl ::= type_expression - -...where type expression is extended to allow ^ as a Block reference (pointer) where * is allowed as a function reference (pointer). - -The following Block literal: - ^ void (void) { printf("hello world\n"); } - -...produces a reference to a Block with no arguments with no return value. - -The return type is optional and is inferred from the return statements. If the return statements return a value, they all must return a value of the same type. If there is no value returned the inferred type of the Block is void; otherwise it is the type of the return statement value. - -If the return type is omitted and the argument list is ( void ), the ( void ) argument list may also be omitted. - -So: - ^ ( void ) { printf("hello world\n"); } - -...and: - ^ { printf("hello world\n"); } - -...are exactly equivalent constructs for the same expression. - -The type_expression extends C expression parsing to accommodate Block reference declarations as it accommodates function pointer declarations. - -Given: - typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char); - pointerToFunctionThatReturnsIntWithCharArg functionPointer; - - ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; } - -...and: - ^ int ((*)(float x))(char) { return functionPointer; } - -...are equivalent expressions, as is: - - ^(float x) { return functionPointer; } - -[returnfunctionptr.c] - -The compound statement body establishes a new lexical scope within that of its parent. Variables used within the scope of the compound statement are bound to the Block in the normal manner with the exception of those in automatic (stack) storage. Thus one may access functions and global variables as one would expect, as well as static local variables. [testme] - -Local automatic (stack) variables referenced within the compound statement of a Block are imported and captured by the Block as const copies. The capture (binding) is performed at the time of the Block literal expression evaluation. - -The lifetime of variables declared in a Block is that of a function; each activation frame contains a new copy of variables declared within the local scope of the Block. Such variable declarations should be allowed anywhere [testme] rather than only when C99 parsing is requested, including for statements. [testme] - -Block literal expressions may occur within Block literal expressions (nest) and all variables captured by any nested blocks are implicitly also captured in the scopes of their enclosing Blocks. - -A Block literal expression may be used as the initialization value for Block variables at global or local static scope. - - -The Invoke Operator - -Blocks are invoked using function call syntax with a list of expression parameters of types corresponding to the declaration and returning a result type also according to the declaration. Given: - int (^x)(char); - void (^z)(void); - int (^(*y))(char) = &x; - -...the following are all legal Block invocations: - x('a'); - (*y)('a'); - (true ? x : *y)('a') - - -The Copy and Release Operations - -The compiler and runtime provide copy and release operations for Block references that create and, in matched use, release allocated storage for referenced Blocks. - -The copy operation Block_copy() is styled as a function that takes an arbitrary Block reference and returns a Block reference of the same type. The release operation, Block_release(), is styled as a function that takes an arbitrary Block reference and, if dynamically matched to a Block copy operation, allows recovery of the referenced allocated memory. - - -The __block Storage Qualifier - -In addition to the new Block type we also introduce a new storage qualifier, __block, for local variables. [testme: a __block declaration within a block literal] The __block storage qualifier is mutually exclusive to the existing local storage qualifiers auto, register, and static.[testme] Variables qualified by __block act as if they were in allocated storage and this storage is automatically recovered after last use of said variable. An implementation may choose an optimization where the storage is initially automatic and only "moved" to allocated (heap) storage upon a Block_copy of a referencing Block. Such variables may be mutated as normal variables are. - -In the case where a __block variable is a Block one must assume that the __block variable resides in allocated storage and as such is assumed to reference a Block that is also in allocated storage (that it is the result of a Block_copy operation). Despite this there is no provision to do a Block_copy or a Block_release if an implementation provides initial automatic storage for Blocks. This is due to the inherent race condition of potentially several threads trying to update the shared variable and the need for synchronization around disposing of older values and copying new ones. Such synchronization is beyond the scope of this language specification. - - -Control Flow - -The compound statement of a Block is treated much like a function body with respect to control flow in that goto, break, and continue do not escape the Block. Exceptions are treated "normally" in that when thrown they pop stack frames until a catch clause is found. - - -Objective-C Extensions - -Objective-C extends the definition of a Block reference type to be that also of id. A variable or expression of Block type may be messaged or used as a parameter wherever an id may be. The converse is also true. Block references may thus appear as properties and are subject to the assign, retain, and copy attribute logic that is reserved for objects. - -All Blocks are constructed to be Objective-C objects regardless of whether the Objective-C runtime is operational in the program or not. Blocks using automatic (stack) memory are objects and may be messaged, although they may not be assigned into __weak locations if garbage collection is enabled. - -Within a Block literal expression within a method definition references to instance variables are also imported into the lexical scope of the compound statement. These variables are implicitly qualified as references from self, and so self is imported as a const copy. The net effect is that instance variables can be mutated. - -The Block_copy operator retains all objects held in variables of automatic storage referenced within the Block expression (or form strong references if running under garbage collection). Object variables of __block storage type are assumed to hold normal pointers with no provision for retain and release messages. - -Foundation defines (and supplies) -copy and -release methods for Blocks. - -In the Objective-C and Objective-C++ languages, we allow the __weak specifier for __block variables of object type. If garbage collection is not enabled, this qualifier causes these variables to be kept without retain messages being sent. This knowingly leads to dangling pointers if the Block (or a copy) outlives the lifetime of this object. - -In garbage collected environments, the __weak variable is set to nil when the object it references is collected, as long as the __block variable resides in the heap (either by default or via Block_copy()). The initial Apple implementation does in fact start __block variables on the stack and migrate them to the heap only as a result of a Block_copy() operation. - -It is a runtime error to attempt to assign a reference to a stack-based Block into any storage marked __weak, including __weak __block variables. - - -C++ Extensions - -Block literal expressions within functions are extended to allow const use of C++ objects, pointers, or references held in automatic storage. - -For example, given class Foo with member function fighter(void): - Foo foo; - Foo &fooRef = foo; - Foo *fooPtr = &foo; - -...a Block that used foo would import the variables as const variations: - const Foo block_foo = foo; // const copy constructor - const Foo &block_fooRef = fooRef; - const Foo *block_fooPtr = fooPtr; - -Stack-local objects are copied into a Block via a copy const constructor. If no such constructor exists, it is considered an error to reference such objects from within the Block compound statements. A destructor is run as control leaves the compound statement that contains the Block literal expression. - -If a Block originates on the stack, a const copy constructor of the stack-based Block const copy is performed when a Block_copy operation is called; when the last Block_release (or subsequently GC) occurs, a destructor is run on the heap copy. - -Variables declared as residing in __block storage may be initially allocated in the heap or may first appear on the stack and be copied to the heap as a result of a Block_copy() operation. When copied from the stack, a normal copy constructor is used to initialize the heap-based version from the original stack version. The destructor for a const copied object is run at the normal end of scope. The destructor for any initial stack based version is also called at normal end of scope. - -Within a member function, access to member functions and variables is done via an implicit const copy of a this pointer. - -Member variables that are Blocks may not be overloaded by the types of their arguments. - diff --git a/docs/DriverArchitecture.png b/docs/DriverArchitecture.png deleted file mode 100644 index 056a70a98f..0000000000 Binary files a/docs/DriverArchitecture.png and /dev/null differ diff --git a/docs/DriverInternals.html b/docs/DriverInternals.html deleted file mode 100644 index a7d2da3771..0000000000 --- a/docs/DriverInternals.html +++ /dev/null @@ -1,517 +0,0 @@ - - - Clang Driver Manual - - - - - - - - -
- -

Driver Design & Internals

- - - - - -

Introduction

- - -

This document describes the Clang driver. The purpose of this - document is to describe both the motivation and design goals - for the driver, as well as details of the internal - implementation.

- - -

Features and Goals

- - -

The Clang driver is intended to be a production quality - compiler driver providing access to the Clang compiler and - tools, with a command line interface which is compatible with - the gcc driver.

- -

Although the driver is part of and driven by the Clang - project, it is logically a separate tool which shares many of - the same goals as Clang:

- -

Features:

- - - -

GCC Compatibility

- - -

The number one goal of the driver is to ease the adoption of - Clang by allowing users to drop Clang into a build system - which was designed to call GCC. Although this makes the driver - much more complicated than might otherwise be necessary, we - decided that being very compatible with the gcc command line - interface was worth it in order to allow users to quickly test - clang on their projects.

- - -

Flexible

- - -

The driver was designed to be flexible and easily accomodate - new uses as we grow the clang and LLVM infrastructure. As one - example, the driver can easily support the introduction of - tools which have an integrated assembler; something we hope to - add to LLVM in the future.

- -

Similarly, most of the driver functionality is kept in a - library which can be used to build other tools which want to - implement or accept a gcc like interface.

- - -

Low Overhead

- - -

The driver should have as little overhead as possible. In - practice, we found that the gcc driver by itself incurred a - small but meaningful overhead when compiling many small - files. The driver doesn't do much work compared to a - compilation, but we have tried to keep it as efficient as - possible by following a few simple principles:

-
    -
  • Avoid memory allocation and string copying when - possible.
    • - -
  • Don't parse arguments more than once.
    • - -
  • Provide a few simple interfaces for efficiently searching - arguments.
    • -
- - -

Simple

- - -

Finally, the driver was designed to be "as simple as - possible", given the other goals. Notably, trying to be - completely compatible with the gcc driver adds a significant - amount of complexity. However, the design of the driver - attempts to mitigate this complexity by dividing the process - into a number of independent stages instead of a single - monolithic task.

- - -

Internal Design and Implementation

- - - - - -

Internals Introduction

- - -

In order to satisfy the stated goals, the driver was designed - to completely subsume the functionality of the gcc executable; - that is, the driver should not need to delegate to gcc to - perform subtasks. On Darwin, this implies that the Clang - driver also subsumes the gcc driver-driver, which is used to - implement support for building universal images (binaries and - object files). This also implies that the driver should be - able to call the language specific compilers (e.g. cc1) - directly, which means that it must have enough information to - forward command line arguments to child processes - correctly.

- - -

Design Overview

- - -

The diagram below shows the significant components of the - driver architecture and how they relate to one another. The - orange components represent concrete data structures built by - the driver, the green components indicate conceptually - distinct stages which manipulate these data structures, and - the blue components are important helper classes.

- -
- - - -
- - -

Driver Stages

- - -

The driver functionality is conceptually divided into five stages:

- -
    -
  1. - Parse: Option Parsing - -

    The command line argument strings are decomposed into - arguments (Arg instances). The driver expects to - understand all available options, although there is some - facility for just passing certain classes of options - through (like -Wl,).

    - -

    Each argument corresponds to exactly one - abstract Option definition, which describes how - the option is parsed along with some additional - metadata. The Arg instances themselves are lightweight and - merely contain enough information for clients to determine - which option they correspond to and their values (if they - have additional parameters).

    - -

    For example, a command line like "-Ifoo -I foo" would - parse to two Arg instances (a JoinedArg and a SeparateArg - instance), but each would refer to the same Option.

    - -

    Options are lazily created in order to avoid populating - all Option classes when the driver is loaded. Most of the - driver code only needs to deal with options by their - unique ID (e.g., options::OPT_I),

    - -

    Arg instances themselves do not generally store the - values of parameters. In many cases, this would - simply result in creating unnecessary string - copies. Instead, Arg instances are always embedded inside - an ArgList structure, which contains the original vector - of argument strings. Each Arg itself only needs to contain - an index into this vector instead of storing its values - directly.

    - -

    The clang driver can dump the results of this - stage using the -ccc-print-options flag (which - must preceed any actual command line arguments). For - example:

    - 
    -            $ clang -ccc-print-options -Xarch_i386 -fomit-frame-pointer -Wa,-fast -Ifoo -I foo t.c
-            Option 0 - Name: "-Xarch_", Values: {"i386", "-fomit-frame-pointer"}
-            Option 1 - Name: "-Wa,", Values: {"-fast"}
-            Option 2 - Name: "-I", Values: {"foo"}
-            Option 3 - Name: "-I", Values: {"foo"}
-            Option 4 - Name: "<input>", Values: {"t.c"}
-
    - -

    After this stage is complete the command line should be - broken down into well defined option objects with their - appropriate parameters. Subsequent stages should rarely, - if ever, need to do any string processing.

    -
    2. - -
  2. - Pipeline: Compilation Job Construction - -

    Once the arguments are parsed, the tree of subprocess - jobs needed for the desired compilation sequence are - 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 - one or more top-level actions, each of which generally - corresponds to a single output (for example, an object or - linked executable).

    - -

    The majority of Actions correspond to actual tasks, - however there are two special Actions. The first is - InputAction, which simply serves to adapt an input - argument for use as an input to other Actions. The second - is BindArchAction, which conceptually alters the - architecture to be used for all of its input Actions.

    - -

    The clang driver can dump the results of this - stage using the -ccc-print-phases flag. For - example:

    - 
    -            $ clang -ccc-print-phases -x c t.c -x assembler t.s
-            0: input, "t.c", c
-            1: preprocessor, {0}, cpp-output
-            2: compiler, {1}, assembler
-            3: assembler, {2}, object
-            4: input, "t.s", assembler
-            5: assembler, {4}, object
-            6: linker, {3, 5}, image
-
    -

    Here the driver is constructing seven distinct actions, - four to compile the "t.c" input into an object file, two to - assemble the "t.s" input, and one to link them together.

    - -

    A rather different compilation pipeline is shown here; in - this example there are two top level actions to compile - the input files into two separate object files, where each - object file is built using lipo to merge results - built for two separate architectures.

    - 
    -            $ clang -ccc-print-phases -c -arch i386 -arch x86_64 t0.c t1.c
-            0: input, "t0.c", c
-            1: preprocessor, {0}, cpp-output
-            2: compiler, {1}, assembler
-            3: assembler, {2}, object
-            4: bind-arch, "i386", {3}, object
-            5: bind-arch, "x86_64", {3}, object
-            6: lipo, {4, 5}, object
-            7: input, "t1.c", c
-            8: preprocessor, {7}, cpp-output
-            9: compiler, {8}, assembler
-            10: assembler, {9}, object
-            11: bind-arch, "i386", {10}, object
-            12: bind-arch, "x86_64", {10}, object
-            13: lipo, {11, 12}, object
-
    - -

    After this stage is complete the compilation process is - divided into a simple set of actions which need to be - performed to produce intermediate or final outputs (in - some cases, like -fsyntax-only, there is no - "real" final output). Phases are well known compilation - steps, such as "preprocess", "compile", "assemble", - "link", etc.

    -
    3. - -
  3. - Bind: Tool & Filename Selection - -

    This stage (in conjunction with the Translate stage) - turns the tree of Actions into a list of actual subprocess - 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 selected the driver interacts with the tool - to see if it can match additional actions (for example, by - having an integrated preprocessor). - -

    Once Tools have been selected for all actions, the driver - determines how the tools should be connected (for example, - using an inprocess module, pipes, temporary files, or user - provided filenames). If an output file is required, the - driver also computes the appropriate file name (the suffix - and file location depend on the input types and options - such as -save-temps). - -

    The driver interacts with a ToolChain to perform the Tool - bindings. Each ToolChain contains information about all - the tools needed for compilation for a particular - architecture, platform, and operating system. A single - driver invocation may query multiple ToolChains during one - compilation in order to interact with tools for separate - architectures.

    - -

    The results of this stage are not computed directly, but - the driver can print the results via - the -ccc-print-bindings option. For example:

    - 
    -            $ clang -ccc-print-bindings -arch i386 -arch ppc t0.c
-            # "i386-apple-darwin9" - "clang", inputs: ["t0.c"], output: "/tmp/cc-Sn4RKF.s"
-            # "i386-apple-darwin9" - "darwin::Assemble", inputs: ["/tmp/cc-Sn4RKF.s"], output: "/tmp/cc-gvSnbS.o"
-            # "i386-apple-darwin9" - "darwin::Link", inputs: ["/tmp/cc-gvSnbS.o"], output: "/tmp/cc-jgHQxi.out"
-            # "ppc-apple-darwin9" - "gcc::Compile", inputs: ["t0.c"], output: "/tmp/cc-Q0bTox.s"
-            # "ppc-apple-darwin9" - "gcc::Assemble", inputs: ["/tmp/cc-Q0bTox.s"], output: "/tmp/cc-WCdicw.o"
-            # "ppc-apple-darwin9" - "gcc::Link", inputs: ["/tmp/cc-WCdicw.o"], output: "/tmp/cc-HHBEBh.out"
-            # "i386-apple-darwin9" - "darwin::Lipo", inputs: ["/tmp/cc-jgHQxi.out", "/tmp/cc-HHBEBh.out"], output: "a.out"
-
    - -

    This shows the tool chain, tool, inputs and outputs which - have been bound for this compilation sequence. Here clang - is being used to compile t0.c on the i386 architecture and - darwin specific versions of the tools are being used to - assemble and link the result, but generic gcc versions of - the tools are being used on PowerPC.

    -
    4. - -
  4. - Translate: Tool Specific Argument Translation - -

    Once a Tool has been selected to perform a particular - Action, the Tool must construct concrete Jobs which will be - executed during compilation. The main work is in translating - from the gcc style command line options to whatever options - the subprocess expects.

    - -

    Some tools, such as the assembler, only interact with a - handful of arguments and just determine the path of the - executable to call and pass on their input and output - arguments. Others, like the compiler or the linker, may - translate a large number of arguments in addition.

    - -

    The ArgList class provides a number of simple helper - methods to assist with translating arguments; for example, - to pass on only the last of arguments corresponding to some - option, or all arguments for an option.

    - -

    The result of this stage is a list of Jobs (executable - paths and argument strings) to execute.

    -
    5. - -
  5. - Execute -

    Finally, the compilation pipeline is executed. This is - mostly straightforward, although there is some interaction - with options - like -pipe, -pass-exit-codes - and -time.

    -
    6. - -
- - -

Additional Notes

- - -

The Compilation Object

- -

The driver constructs a Compilation object for each set of - command line arguments. The Driver itself is intended to 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.

- -

The Compilation object holds information that is particular - to each compilation sequence. For example, the list of used - temporary files (which must be removed once compilation is - finished) and result files (which should be removed if - compilation files).

- -

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 - driver.

- -

ToolChain Argument Translation

- -

In order to match gcc very closely, the clang driver - currently allows tool chains to perform their own translation of - the argument list (into a new ArgList data structure). Although - this allows the clang driver to match gcc easily, it also makes - the driver operation much harder to understand (since the Tools - 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 Tool - argument translation is done after the arguments have been - translated.

- -

A long term goal is to remove this tool chain specific - translation, and instead force each tool to change its own logic - to do the right thing on the untranslated original arguments.

- -

Unused Argument Warnings

-

The driver operates by parsing all arguments but giving Tools - the opportunity to choose which arguments to pass on. One - downside of this infrastructure is that if the user misspells - some option, or is confused about which options to use, some - command line arguments the user really cared about may go - unused. This problem is particularly important when using - clang as a compiler, since the clang compiler does not support - anywhere near all the options that gcc does, and we want to make - sure users know which ones are being used.

- -

To support this, the driver maintains a bit associated with - each argument of whether it has been used (at all) during the - compilation. This bit usually doesn't need to be set by hand, - as the key ArgList accessors will set it automatically.

- -

When a compilation is successful (there are no errors), the - driver checks the bit and emits an "unused argument" warning for - any arguments which were never accessed. This is conservative - (the argument may not have been used to do what the user wanted) - but still catches the most obvious cases.

- - -

Relation to GCC Driver Concepts

- - -

For those familiar with the gcc driver, this section provides - a brief overview of how things from the gcc driver map to the - clang driver.

- -
    -
  • - Driver Driver -

    The driver driver is fully integrated into the clang - driver. The driver simply constructs additional Actions to - bind the architecture during the Pipeline - phase. The tool chain specific argument translation is - responsible for handling -Xarch_.

    - -

    The one caveat is that this approach - requires -Xarch_ not be used to alter the - compilation itself (for example, one cannot - provide -S as an -Xarch_ argument). The - driver attempts to reject such invocations, and overall - there isn't a good reason to abuse -Xarch_ to - that end in practice.

    - -

    The upside is that the clang driver is more efficient and - does little extra work to support universal builds. It also - provides better error reporting and UI consistency.

    -
    • - -
  • - Specs -

    The clang driver has no direct correspondant for - "specs". The majority of the functionality that is - embedded in specs is in the Tool specific argument - translation routines. The parts of specs which control the - compilation pipeline are generally part of - the Pipeline stage.

    -
    • - -
  • - Toolchains -

    The gcc driver has no direct understanding of tool - chains. Each gcc binary roughly corresponds to the - information which is embedded inside a single - ToolChain.

    - -

    The clang driver is intended to be portable and support - complex compilation environments. All platform and tool - chain specific code should be protected behind either - abstract or well defined interfaces (such as whether the - platform supports use as a driver driver).

    -
    • -
-
- - diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html deleted file mode 100644 index daec6b0194..0000000000 --- a/docs/InternalsManual.html +++ /dev/null @@ -1,1681 +0,0 @@ - - -"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 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, a SourceLocation to -"put the caret", an English translation associated with it, and a severity (e.g. -WARNING or ERROR). They can also optionally include a number -of arguments to the dianostic (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 diagonstic 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.

- - -

The Diagnostic*Kinds.def files

- - -

Diagnostics are created by adding an entry to one of the -clang/Basic/Diagnostic*Kinds.def files, depending on what library will -be using it. This file encodes the unique ID of the -diagnostic (as an enum, the first argument), the severity of the diagnostic -(second argument) and the English translation + format string.

- -

There is little sanity with the naming of the unique ID's right now. Some -start with err_, warn_, ext_ to encode the severity into the name. Since the -enum is referenced in the C++ code that produces the diagnostic, it is somewhat -useful for it to be reasonably short.

- -

The severity of the diagnostic comes from the set {NOTE, -WARNING, EXTENSION, EXTWARN, ERROR}. The -ERROR severity is used for diagnostics indicating the program is never -acceptable under any circumstances. When an error is emitted, the AST for the -input code may not be fully built. The EXTENSION and EXTWARN -severities are used for extensions to the language that Clang accepts. This -means that Clang fully understands and can represent them in the AST, but we -produce diagnostics to tell the user their code is non-portable. The difference -is that the former are ignored by default, and the later warn by default. The -WARNING severity is used for constructs that are valid in the currently -selected source language but that are dubious in some way. The NOTE -level is used to staple more information onto previous diagnostics.

- -

These severities are mapped into a smaller set (the -Diagnostic::Level enum, {Ignored, Note, Warning, -Error, Fatal }) of output levels by the diagnostics -subsystem based on various configuration options. Clang internally supports a -fully fine grained mapping mechanism that allows you to map almost any -diagnostic to the output level that you want. The only diagnostics that cannot -be mapped are NOTEs, which always follow the severity of the previously -emitted diagnostic and ERRORs, which can only be mapped to -Fatal (it is not possible to turn an error into a warning, -for example).

- -

Diagnostic mappings are used in many ways. For example, if the user -specifies -pedantic, EXTENSION maps to Warning, if -they specify -pedantic-errors, it turns into Error. This is -used to implement options like -Wunused_macros, -Wundef etc. -

- -

-Mapping to Fatal should only be used for diagnostics that are -considered so severe that error recovery won't be able to recover sensibly from -them (thus spewing a ton of bogus errors). One example of this class of error -are failure to #include a file. -

- - -

The Format String

- - -

The format string for the diagnostic is very simple, but it has some power. -It takes the form of a string in English with markers that indicate where and -how arguments to the diagnostic are inserted and formatted. For example, here -are some simple format strings:

- -
-  "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)"
-
- -

These examples show some important points of format strings. You can use any - plain ASCII character in the diagnostic string except "%" without a problem, - but these are C strings, so you have to use and be aware of all the C escape - sequences (as in the second example). If you want to produce a "%" in the - output, use the "%%" escape sequence, like the third diagnostic. Finally, - Clang uses the "%...[digit]" sequences to specify where and how arguments to - the diagnostic are formatted.

- -

Arguments to the diagnostic are numbered according to how they are specified - by the C++ code that produces them, and are - referenced by %0 .. %9. If you have more than 10 arguments - to your diagnostic, you are doing something wrong :). Unlike printf, there - is no requirement that arguments to the diagnostic end up in the output in - the same order as they are specified, you could have a format string with - "%1 %0" that swaps them, for example. The text in between the - percent and digit are formatting instructions. If there are no instructions, - the argument is just turned into a string and substituted in.

- -

Here are some "best practices" for writing the English format string:

- -
    -
  • Keep the string short. It should ideally fit in the 80 column limit of the - DiagnosticKinds.def file. This avoids the diagnostic wrapping when - printed, and forces you to think about the important point you are conveying - with the diagnostic.
    • -
  • Take advantage of location information. The user will be able to see the - line and location of the caret, so you don't need to tell them that the - problem is with the 4th argument to the function: just point to it.
    • -
  • Do not capitalize the diagnostic string, and do not end it with a - period.
    • -
  • If you need to quote something in the diagnostic string, use single - quotes.
    • -
- -

Diagnostics should never take random English strings as arguments: you -shouldn't use "you have a problem with %0" and pass in things like -"your argument" or "your return value" as arguments. Doing -this prevents translating the Clang diagnostics to -other languages (because they'll get random English words in their otherwise -localized diagnostic). The exceptions to this are C/C++ language keywords -(e.g. auto, const, mutable, etc) and C/C++ operators (/=). Note -that things like "pointer" and "reference" are not keywords. On the other -hand, you can include anything that comes from the user's source code, -including variable names, types, labels, etc. The 'select' format can be -used to achieve this sort of thing in a localizable way, see below.

- - -

Formatting a Diagnostic Argument

- - -

Arguments to diagnostics are fully typed internally, and come from a couple -different classes: integers, types, names, and random strings. Depending on -the class of the argument, it can be optionally formatted in different ways. -This gives the DiagnosticClient information about what the argument means -without requiring it to use a specific presentation (consider this MVC for -Clang :).

- -

Here are the different diagnostic argument formats currently supported by -Clang:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
"s" format
Example:"requires %1 parameter%s1"
Class:Integers
Description:This is a simple formatter for integers that is - useful when producing English diagnostics. When the integer is 1, it prints - as nothing. When the integer is not 1, it prints as "s". This allows some - simple grammatical forms to be to be handled correctly, and eliminates the - need to use gross things like "requires %1 parameter(s)".
"select" format
Example:"must be a %select{unary|binary|unary or binary}2 - operator"
Class:Integers
Description:

This format specifier is used to merge multiple - related diagnostics together into one common one, without requiring the - difference to be specified as an English string argument. Instead of - specifying the string, the diagnostic gets an integer argument and the - format string selects the numbered option. In this case, the "%2" value - must be an integer in the range [0..2]. If it is 0, it prints 'unary', if - it is 1 it prints 'binary' if it is 2, it prints 'unary or binary'. This - allows other language translations to substitute reasonable words (or entire - phrases) based on the semantics of the diagnostic instead of having to do - things textually.

-

The selected string does undergo formatting.

"plural" format
Example:"you have %1 %plural{1:mouse|:mice}1 connected to - your computer"
Class:Integers
Description:

This is a formatter for complex plural forms. - It is designed to handle even the requirements of languages with very - complex plural forms, as many Baltic languages have. The argument consists - of a series of expression/form pairs, separated by ':', where the first form - whose expression evaluates to true is the result of the modifier.

-

An expression can be empty, in which case it is always true. See the - example at the top. Otherwise, it is a series of one or more numeric - conditions, separated by ','. If any condition matches, the expression - matches. Each numeric condition can take one of three forms.

-
    -
  • number: A simple decimal number matches if the argument is the same - as the number. Example: "%plural{1:mouse|:mice}4"
    • -
  • range: A range in square brackets matches if the argument is within - the range. Then range is inclusive on both ends. Example: - "%plural{0:none|1:one|[2,5]:some|:many}2"
    • -
  • modulo: A modulo operator is followed by a number, and - equals sign and either a number or a range. The tests are the - same as for plain - numbers and ranges, but the argument is taken modulo the number first. - Example: "%plural{%100=0:even hundred|%100=[1,50]:lower half|:everything - else}1"
    • -
-

The parser is very unforgiving. A syntax error, even whitespace, will - abort, as will a failure to match the argument against any - expression.

"ordinal" format
Example:"ambiguity in %ordinal0 argument"
Class:Integers
Description:

This is a formatter which represents the - argument number as an ordinal: the value 1 becomes 1st, - 3 becomes 3rd, and so on. Values less than 1 - are not supported.

-

This formatter is currently hard-coded to use English ordinals.

"objcclass" format
Example:"method %objcclass0 not found"
Class:DeclarationName
Description:

This is a simple formatter that indicates the - DeclarationName corresponds to an Objective-C class method selector. As - such, it prints the selector with a leading '+'.

"objcinstance" format
Example:"method %objcinstance0 not found"
Class:DeclarationName
Description:

This is a simple formatter that indicates the - DeclarationName corresponds to an Objective-C instance method selector. As - such, it prints the selector with a leading '-'.

"q" format
Example:"candidate found by name lookup is %q0"
Class:NamedDecl*
Description

This formatter indicates that the fully-qualified name of the declaration should be printed, e.g., "std::vector" rather than "vector".

- -

It is really easy to add format specifiers to the Clang diagnostics system, -but they should be discussed before they are added. If you are creating a lot -of repetitive diagnostics and/or have an idea for a useful formatter, please -bring it up on the cfe-dev mailing list.

- - -

Producing the Diagnostic

- - -

Now that you've created the diagnostic in the DiagnosticKinds.def file, you -need to write the code that detects the condition in question and emits the -new diagnostic. Various components of Clang (e.g. the preprocessor, Sema, -etc) provide a helper function named "Diag". It creates a diagnostic and -accepts the arguments, ranges, and other information that goes along with -it.

- -

For example, the binary expression error comes from code like this:

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

This shows that use of the Diag method: they take a location (a SourceLocation object) and a diagnostic enum value -(which matches the name from DiagnosticKinds.def). If the diagnostic takes -arguments, they are specified with the << operator: the first argument -becomes %0, the second becomes %1, etc. The diagnostic interface allows you to -specify arguments of many different types, including int and -unsigned for integer arguments, const char* and -std::string for string arguments, DeclarationName and -const IdentifierInfo* for names, QualType for types, etc. -SourceRanges are also specified with the << operator, but do not have a -specific ordering requirement.

- -

As you can see, adding and producing a diagnostic is pretty straightforward. -The hard part is deciding exactly what you need to say to help the user, picking -a suitable wording, and providing the information needed to format it correctly. -The good news is that the call site that issues a diagnostic should be -completely independent of how the diagnostic is formatted and in what language -it is rendered. -

- - -

Code Modification Hints

- - -

In some cases, the front end emits diagnostics when it is clear -that some small change to the source code would fix the problem. For -example, a missing semicolon at the end of a statement or a use of -deprecated syntax that is easily rewritten into a more modern form. -Clang tries very hard to emit the diagnostic and recover gracefully -in these and other cases.

- -

However, for these cases where the fix is obvious, the diagnostic -can be annotated with a code -modification "hint" that describes how to change the code referenced -by the diagnostic to fix the problem. For example, it might add the -missing semicolon at the end of the statement or rewrite the use of a -deprecated construct into something more palatable. Here is one such -example C++ front end, where we warn about the right-shift operator -changing meaning from C++98 to C++0x:

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

Here, the code modification hint is suggesting that parentheses be -added, and showing exactly where those parentheses would be inserted -into the source code. The code modification hints themselves describe -what changes to make to the source code in an abstract manner, which -the text diagnostic printer renders as a line of "insertions" below -the caret line. Other diagnostic -clients might choose to render the code differently (e.g., as -markup inline) or even give the user the ability to automatically fix -the problem.

- -

All code modification hints are described by the -CodeModificationHint class, instances of which should be -attached to the diagnostic using the << operator in the same way -that highlighted source ranges and arguments are passed to the -diagnostic. Code modification hints can be created with one of three -constructors:

- -
-
CodeModificationHint::CreateInsertion(Loc, Code)
-
Specifies that the given Code (a string) should be inserted - before the source location Loc.
- -
CodeModificationHint::CreateRemoval(Range)
-
Specifies that the code in the given source Range - should be removed.
- -
CodeModificationHint::CreateReplacement(Range, Code)
-
Specifies that the code in the given source Range - should be removed, and replaced with the given Code string.
-
- - -

The DiagnosticClient Interface

- - -

Once code generates a diagnostic with all of the arguments and the rest of -the relevant information, Clang needs to know what to do with it. As previously -mentioned, the diagnostic machinery goes through some filtering to map a -severity onto a diagnostic level, then (assuming the diagnostic is not mapped to -"Ignore") it invokes an object that implements the DiagnosticClient -interface with the information.

- -

It is possible to implement this interface in many different ways. For -example, the normal Clang DiagnosticClient (named 'TextDiagnosticPrinter') turns -the arguments into strings (according to the various formatting rules), prints -out the file/line/column information and the string, then prints out the line of -code, the source ranges, and the caret. However, this behavior isn't required. -

- -

Another implementation of the DiagnosticClient interface is the -'TextDiagnosticBuffer' class, which is used when Clang is in -verify mode. -Instead of formatting and printing out the diagnostics, this implementation just -captures and remembers the diagnostics as they fly by. Then -verify compares -the list of produced diagnostics to the list of expected ones. If they disagree, -it prints out its own output. -

- -

There are many other possible implementations of this interface, and this is -why we prefer diagnostics to pass down rich structured information in arguments. -For example, an HTML output might want declaration names be linkified to where -they come from in the source. Another example is that a GUI might let you click -on typedefs to expand them. This application would want to pass significantly -more information about types through to the GUI than a simple flat string. The -interface allows this to happen.

- - -

Adding Translations to Clang

- - -

Not possible yet! Diagnostic strings should be written in UTF-8, the client -can translate to the relevant code page if needed. Each translation completely -replaces the format string for the diagnostic.

- - - -

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 spelling location -and it's instantiation 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).

- -

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.

- - -

The Driver Library

- - -

The clang Driver and library are documented here.

- - -

Precompiled Headers

- - -

Clang supports two implementations of precompiled headers. The - default implementation, precompiled headers (PCH) uses a serialized representation - of Clang's internal data structures, encoded with the LLVM bitstream - format. Pretokenized headers (PTH), on the other hand, contain a - serialized representation of the tokens encountered when - preprocessing a header (and anything that header includes).

- - - -

The Frontend Library

- - -

The Frontend library contains functionality useful for building -tools on top of the clang libraries, for example several methods for -outputting diagnostics.

- - -

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 TokenLexer 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 matter. 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. -
    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. -
    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. -
    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 through an Actions module, it is passed around and Sema -intepretes it, based on the type of annotation token.
    • - -
  • 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 a pointer returned by Action::getTypeName(). In the case of the -Sema actions module, this is a Decl* for the type.
    2. - -
  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 returned -by the Action::ActOnCXXGlobalScopeSpecifier and -Action::ActOnCXXNestedNameSpecifier callbacks. In the case of Sema, this is a -DeclContext*.
    3. - -
  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.
    4. - -
- -

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 EOM 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 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. 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 typdefs. 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.

- - -

Canonical Types

- - -

Every instance of the Type class contains a canonical type pointer. For -simple types with no typedefs involved (e.g. "int", "int*", -"int**"), the type just points to itself. For types that have a -typedef somewhere in their structure (e.g. "foo", "foo*", -"foo**", "bar"), the canonical type pointer points to their -structurally equivalent type without any typedefs (e.g. "int", -"int*", "int**", and "int*" respectively).

- -

This design provides a constant time operation (dereferencing the canonical -type pointer) that gives us access to the structure of types. For example, -we can trivially tell that "bar" and "foo*" are the same type by dereferencing -their canonical type pointers and doing a pointer comparison (they both point -to the single "int*" type).

- -

Canonical types and typedef types bring up some complexities that must be -carefully managed. Specifically, the "isa/cast/dyncast" operators generally -shouldn't be used in code that is inspecting the AST. For example, when type -checking the indirection operator (unary '*' on a pointer), the type checker -must verify that the operand has a pointer type. It would not be correct to -check that with "isa<PointerType>(SubExpr->getType())", -because this predicate would fail if the subexpression had a typedef type.

- -

The solution to this problem are a set of helper methods on Type, used to -check their properties. In this case, it would be correct to use -"SubExpr->getType()->isPointerType()" to do the check. This -predicate will return true if the canonical type is a pointer, which is -true any time the type is structurally a pointer type. The only hard part here -is remembering not to use the isa/cast/dyncast operations.

- -

The second problem we face is how to get access to the pointer type once we -know it exists. To continue the example, the result type of the indirection -operator is the pointee type of the subexpression. In order to determine the -type, we need to get the instance of PointerType that best captures the typedef -information in the program. If the type of the expression is literally a -PointerType, we can return that, otherwise we have to dig through the -typedefs to find the pointer type. For example, if the subexpression had type -"foo*", we could return that type as the result. If the subexpression -had type "bar", we want to return "foo*" (note that we do -not want "int*"). In order to provide all of this, Type has -a getAsPointerType() method that checks whether the type is structurally a -PointerType and, if so, returns the best one. If not, it returns a null -pointer.

- -

This structure is somewhat mystical, but after meditating on it, it will -make sense to you :).

- - -

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.

- - -

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 8 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. Note that C++ overloaded operators (e.g., - "operator+") are represented as special kinds of - identifiers. Use IdentifierInfo's getOverloadedOperatorID - function to determine whether an identifier is an overloaded - operator name.
- -
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).
-
- -

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.

- -

Redeclarations and Overloads

-

Within a translation unit, it is common for an entity to be -declared several times. For example, we might declare a function "f" - and then later re-declare it as part of an inlined definition:

- -
-void f(int x, int y, int z = 1);
-
-inline void f(int x, int y, int z) { /* ... */ }
-
- -

The representation of "f" differs in the source-centric and - semantics-centric views of a declaration context. In the - source-centric view, all redeclarations will be present, in the - order they occurred in the source code, making - this view suitable for clients that wish to see the structure of - the source code. In the semantics-centric view, only the most recent "f" - will be found by the lookup, since it effectively replaces the first - declaration of "f".

- -

In the semantics-centric view, overloading of functions is - represented explicitly. For example, given two declarations of a - function "g" that are overloaded, e.g.,

-
-void g();
-void g(int);
-
-

the DeclContext::lookup operation will return - an OverloadedFunctionDecl that contains both - declarations of "g". Clients that perform semantic analysis on a - program that is not concerned with the actual source code will - primarily use this semantics-centric view.

- -

Lexical and Semantic Contexts

-

Each declaration has two potentially different - declaration contexts: a lexical context, which corresponds to - the source-centric view of the declaration context, and - a semantic context, which corresponds to the - semantics-centric view. The lexical context is accessible - via Decl::getLexicalDeclContext while the - semantic context is accessible - via Decl::getDeclContext, both of which return - DeclContext pointers. For most declarations, the two - contexts are identical. For example:

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

Here, the semantic and lexical contexts of X::f are - the DeclContext associated with the - class X (itself stored as a RecordDecl AST - node). However, we can now define X::f out-of-line:

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

This definition of has different lexical and semantic - contexts. The lexical context corresponds to the declaration - context in which the actual declaration occurred in the source - code, e.g., the translation unit containing X. Thus, - this declaration of X::f can be found by traversing - the declarations provided by - [decls_begin(), decls_end()) in the - translation unit.

- -

The semantic context of X::f corresponds to the - class X, since this member function is (semantically) a - member of X. Lookup of the name f into - the DeclContext associated with X will - then return the definition of X::f (including - information about the default argument).

- -

Transparent Declaration Contexts

-

In C and C++, there are several contexts in which names that are - logically declared inside another declaration will actually "leak" - out into the enclosing scope from the perspective of name - lookup. The most obvious instance of this behavior is in - enumeration types, e.g.,

-
-enum Color {
-  Red, 
-  Green,
-  Blue
-};
-
- -

Here, Color is an enumeration, which is a declaration - context that contains the - enumerators Red, Green, - and Blue. Thus, traversing the list of declarations - contained in the enumeration Color will - yield Red, Green, - and Blue. However, outside of the scope - of Color one can name the enumerator Red - without qualifying the name, e.g.,

- -
-Color c = Red;
-
- -

There are other entities in C++ that provide similar behavior. For - example, linkage specifications that use curly braces:

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

For source-level accuracy, we treat the linkage specification and - enumeration type as a - declaration context in which its enclosed declarations ("Red", - "Green", and "Blue"; "f" and "g") - are declared. However, these declarations are visible outside of the - scope of the declaration context.

- -

These language features (and several others, described below) have - roughly the same set of - requirements: declarations are declared within a particular lexical - context, but the declarations are also found via name lookup in - scopes enclosing the declaration itself. This feature is implemented - via transparent declaration contexts - (see DeclContext::isTransparentContext()), whose - declarations are visible in the nearest enclosing non-transparent - declaration context. This means that the lexical context of the - declaration (e.g., an enumerator) will be the - transparent DeclContext itself, as will the semantic - context, but the declaration will be visible in every outer context - up to and including the first non-transparent declaration context (since - transparent declaration contexts can be nested).

- -

The transparent DeclContexts are:

-
    -
  • Enumerations (but not C++0x "scoped enumerations"): - 
    -enum Color { 
-  Red, 
-  Green, 
-  Blue 
-};
-// Red, Green, and Blue are in scope
-
    • -
  • C++ linkage specifications: - 
    -extern "C" {
-  void f(int);
-  void g(int);
-}
-// f and g are in scope
-
    • -
  • Anonymous unions and structs: - 
    -struct LookupTable {
-  bool IsVector;
-  union {
-    std::vector<Item> *Vector;
-    std::set<Item> *Set;
-  };
-};
-
-LookupTable LT;
-LT.Vector = 0; // Okay: finds Vector inside the unnamed union
-
    -
    • -
  • C++0x inline namespaces: -
    -namespace mylib {
-  inline namespace debug {
-    class X;
-  }
-}
-mylib::X *xp; // okay: mylib::X refers to mylib::debug::X
-
    -
    • -
- - -

Multiply-Defined Declaration Contexts

-

C++ namespaces have the interesting--and, so far, unique--property that -the namespace can be defined multiple times, and the declarations -provided by each namespace definition are effectively merged (from -the semantic point of view). For example, the following two code -snippets are semantically indistinguishable:

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

In Clang's representation, the source-centric view of declaration - contexts will actually have two separate NamespaceDecl - nodes in Snippet #1, each of which is a declaration context that - contains a single declaration of "f". However, the semantics-centric - view provided by name lookup into the namespace N for - "f" will return an OverloadedFunctionDecl that contains - both declarations of "f".

- -

DeclContext manages multiply-defined declaration - contexts internally. The - function DeclContext::getPrimaryContext retrieves the - "primary" context for a given DeclContext instance, - which is the DeclContext responsible for maintaining - the lookup table used for the semantics-centric view. Given the - primary context, one can follow the chain - of DeclContext nodes that define additional - declarations via DeclContext::getNextContext. Note that - these functions are used internally within the lookup and insertion - methods of the DeclContext, so the vast majority of - clients can ignore them.

- - -

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.

- - -

Basic Blocks

- - -

Concretely, an instance of CFG is a collection of basic -blocks. Each basic block is an instance of CFGBlock, which -simply contains an ordered sequence of Stmt* (each referring -to statements in the AST). The ordering of statements within a block -indicates unconditional flow of control from one statement to the -next. Conditional control-flow -is represented using edges between basic blocks. The statements -within a given CFGBlock can be traversed using -the CFGBlock::*iterator interface.

- -

-A CFG object owns the instances of CFGBlock within -the control-flow graph it represents. Each CFGBlock within a -CFG is also uniquely numbered (accessible -via CFGBlock::getBlockID()). Currently the number is -based on the ordering the blocks were created, but no assumptions -should be made on how CFGBlocks are numbered other than their -numbers are unique and that they are numbered from 0..N-1 (where N is -the number of basic blocks in the CFG).

- - -

Entry and Exit Blocks

- - -Each instance of CFG contains two special blocks: -an entry block (accessible via CFG::getEntry()), which -has no incoming edges, and an exit block (accessible -via CFG::getExit()), which has no outgoing edges. Neither -block contains any statements, and they serve the role of providing a -clear entrance and exit for a body of code such as a function body. -The presence of these empty blocks greatly simplifies the -implementation of many analyses built on top of CFGs. - - -

Conditional Control-Flow

- - -

Conditional control-flow (such as those induced by if-statements -and loops) is represented as edges between CFGBlocks. -Because different C language constructs can induce control-flow, -each CFGBlock also records an extra Stmt* that -represents the terminator of the block. A terminator is simply -the statement that caused the control-flow, and is used to identify -the nature of the conditional control-flow between blocks. For -example, in the case of an if-statement, the terminator refers to -the IfStmt object in the AST that represented the given -branch.

- -

To illustrate, consider the following code example:

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

After invoking the parser+semantic analyzer on this code fragment, -the AST of the body of foo is referenced by a -single Stmt*. We can then construct an instance -of CFG representing the control-flow graph of this function -body by single call to a static class method:

- - -  Stmt* FooBody = ...
-  CFG* FooCFG = CFG::buildCFG(FooBody); - - -

It is the responsibility of the caller of CFG::buildCFG -to delete the returned CFG* when the CFG is no -longer needed.

- -

Along with providing an interface to iterate over -its CFGBlocks, the CFG class also provides methods -that are useful for debugging and visualizing CFGs. For example, the -method -CFG::dump() dumps a pretty-printed version of the CFG to -standard error. This is especially useful when one is using a -debugger such as gdb. For example, here is the output -of FooCFG->dump():

- - - [ 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): - - -

For each block, the pretty-printed output displays for each block -the number of predecessor blocks (blocks that have outgoing -control-flow to the given block) and successor blocks (blocks -that have control-flow that have incoming control-flow from the given -block). We can also clearly see the special entry and exit blocks at -the beginning and end of the pretty-printed output. For the entry -block (block B5), the number of predecessor blocks is 0, while for the -exit block (block B0) the number of successor blocks is 0.

- -

The most interesting block here is B4, whose outgoing control-flow -represents the branching caused by the sole if-statement -in foo. Of particular interest is the second statement in -the block, (x > 2), and the terminator, printed -as if [B4.2]. The second statement represents the -evaluation of the condition of the if-statement, which occurs before -the actual branching of control-flow. Within the CFGBlock -for B4, the Stmt* for the second statement refers to the -actual expression in the AST for (x > 2). Thus -pointers to subclasses of Expr can appear in the list of -statements in a block, and not just subclasses of Stmt that -refer to proper C statements.

- -

The terminator of block B4 is a pointer to the IfStmt -object in the AST. The pretty-printer outputs if -[B4.2] because the condition expression of the if-statement -has an actual place in the basic block, and thus the terminator is -essentially -referring to the expression that is the second statement of -block B4 (i.e., B4.2). In this manner, conditions for control-flow -(which also includes conditions for loops and switch statements) are -hoisted into the actual basic block.

- - - - - - - - - -

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 -unfortuate 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.

- - -

Implementation Approach

- - -

After trying several different approaches, we've finally converged on a -design (Note, at the time of this writing, not all of this has been implemented, -consider this a design goal!). Our basic approach is to define a single -recursive method evaluation method (Expr::Evaluate), which is -implemented in AST/ExprConstant.cpp. Given an expression with 'scalar' -type (integer, fp, complex, or pointer) this method returns the following -information:

- -
    -
  • Whether the expression is an integer constant expression, a general - constant that was folded but has no side effects, a general constant that - was folded but that does have side effects, or an uncomputable/unfoldable - value. -
    • -
  • If the expression was computable in any way, this method returns the APValue - for the result of the expression.
    • -
  • If the expression is not evaluatable at all, this method returns - information on one of the problems with the expression. This includes a - SourceLocation for where the problem is, and a diagnostic ID that explains - the problem. The diagnostic should be have ERROR type.
    • -
  • If the expression is not an integer constant expression, this method returns - information on one of the problems with the expression. This includes a - SourceLocation for where the problem is, and a diagnostic ID that explains - the problem. The diagnostic should be have EXTENSION type.
    • -
- -

This information gives various clients the flexibility that they want, and we -will eventually have some helper methods for various extensions. For example, -Sema should have a Sema::VerifyIntegerConstantExpression method, which -calls Evaluate on the expression. If the expression is not foldable, the error -is emitted, and it would return true. If the expression is not an i-c-e, the -EXTENSION diagnostic is emitted. Finally it would return false to indicate that -the AST is ok.

- -

Other clients can use the information in other ways, for example, codegen can -just use expressions that are foldable in any way.

- - -

Extensions

- - -

This section describes how some of the various extensions Clang supports -interacts with constant evaluation:

- -
    -
  • __extension__: The expression form of this extension causes - any evaluatable subexpression to be accepted as an integer constant - expression.
    • -
  • __builtin_constant_p: This returns true (as a integer - constant expression) if the operand is any evaluatable constant. As a - special case, if __builtin_constant_p is the (potentially - parenthesized) condition of a conditional operator expression ("?:"), only - the true side of the conditional operator is considered, and it is evaluated - with full constant folding.
    • -
  • __builtin_choose_expr: The condition is required to be an - integer constant expression, but we accept any constant as an "extension of - an extension". This only evaluates one operand depending on which way the - condition evaluates.
    • -
  • __builtin_classify_type: This always returns an integer - constant expression.
    • -
  • __builtin_inf,nan,..: These are treated just like a - floating-point literal.
    • -
  • __builtin_abs,copysign,..: These are constant folded as - general constant expressions.
    • -
- - - - -
- - diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html deleted file mode 100644 index 838b65f27b..0000000000 --- a/docs/LanguageExtensions.html +++ /dev/null @@ -1,658 +0,0 @@ - - -Clang Language Extensions - - - - - - - - -
- -

Clang Language Extensions

- - - - -

Introduction

- - -

This document describes the language extensions provided by Clang. In -addition to the language extensions listed here, Clang aims to support a broad -range of GCC extensions. Please see the GCC manual for -more information on these extensions.

- - -

Feature Checking Macros

- - -

Language extensions can be very useful, but only if you know you can depend -on them. In order to allow fine-grain features checks, we support two builtin -function-like macros. This allows you to directly test for a feature in your -code without having to resort to something like autoconf or fragile "compiler -version checks".

- - -

__has_builtin

- - -

This function-like macro takes a single identifier argument that is the name -of a builtin function. It evaluates to 1 if the builtin is supported or 0 if -not. It can be used like this:

- -
-
-#ifndef __has_builtin         // Optional of course.
-  #define __has_builtin(x) 0  // Compatibility with non-clang compilers.
-#endif
-
-...
-#if __has_builtin(__builtin_trap)
-  __builtin_trap();
-#else
-  abort();
-#endif
-...
-
-
- - - -

__has_feature

- - -

This function-like macro takes a single identifier argument that is the name -of a feature. It evaluates to 1 if the feature is supported or 0 if not. It -can be used like this:

- -
-
-#ifndef __has_feature         // Optional of course.
-  #define __has_feature(x) 0  // Compatibility with non-clang compilers.
-#endif
-
-...
-#if __has_feature(attribute_overloadable) || \
-    __has_feature(blocks)
-...
-#endif
-...
-
-
- -

The feature tag is described along with the language feature below.

- - -

Include File Checking Macros

- - -

Not all developments systems have the same include files. -The __has_include and -__has_include_next macros allow you to -check for the existence of an include file before doing -a possibly failing #include directive.

- - -

__has_include

- - -

This function-like macro takes a single file name string argument that -is the name of an include file. It evaluates to 1 if the file can -be found using the include paths, or 0 otherwise:

- -
-
-// Note the two possible file name string formats.
-#if __has_include("myinclude.h") && __has_include(<stdint.h>)
-# include "myinclude.h"
-#endif
-
-// To avoid problem with non-clang compilers not having this macro.
-#if defined(__has_include) && __has_include("myinclude.h")
-# include "myinclude.h"
-#endif
-
-
- -

To test for this feature, use #if defined(__has_include).

- - -

__has_include_next

- - -

This function-like macro takes a single file name string argument that -is the name of an include file. It is like __has_include except that it -looks for the second instance of the given file found in the include -paths. It evaluates to 1 if the second instance of the file can -be found using the include paths, or 0 otherwise:

- -
-
-// Note the two possible file name string formats.
-#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
-# include_next "myinclude.h"
-#endif
-
-// To avoid problem with non-clang compilers not having this macro.
-#if defined(__has_include_next) && __has_include_next("myinclude.h")
-# include_next "myinclude.h"
-#endif
-
-
- -

Note that __has_include_next, like the GNU extension -#include_next directive, is intended for use in headers only, -and will issue a warning if used in the top-level compilation -file. A warning will also be issued if an absolute path -is used in the file argument.

- - -

Builtin Macros

- - -
-
__BASE_FILE__
-
Defined to a string that contains the name of the main input - file passed to Clang.
- -
__COUNTER__
-
Defined to an integer value that starts at zero and is - incremented each time the __COUNTER__ macro is - expanded.
- -
__INCLUDE_LEVEL__
-
Defined to an integral value that is the include depth of the - file currently being translated. For the main file, this value is - zero.
- -
__TIMESTAMP__
-
Defined to the date and time of the last modification of the - current source file.
- -
__clang__
-
Defined when compiling with Clang
- -
__clang_major__
-
Defined to the major version number of Clang (e.g., the 2 in - 2.0.1).
- -
__clang_minor__
-
Defined to the minor version number of Clang (e.g., the 0 in - 2.0.1).
- -
__clang_patchlevel__
-
Defined to the patch level of Clang (e.g., the 1 in 2.0.1).
- -
__clang_version__
-
Defined to a string that captures the Clang version, including - the Subversion tag or revision number, e.g., "1.5 (trunk - 102332)".
-
- - -

Vectors and Extended Vectors

- - -

Supports the GCC vector extensions, plus some stuff like V[1].

- -

Also supports ext_vector, which additionally support for V.xyzw -syntax and other tidbits as seen in OpenCL. An example is:

- -
-
-typedef float float4 __attribute__((ext_vector_type(4)));
-typedef float float2 __attribute__((ext_vector_type(2)));
-
-float4 foo(float2 a, float2 b) {
-  float4 c;
-  c.xz = a;
-  c.yw = b;
-  return c;
-}
-
- -

Query for this feature with __has_feature(attribute_ext_vector_type).

- -

See also __builtin_shufflevector.

- - -

Checks for Standard Language Features

- - -

The __has_feature macro can be used to query if certain standard language features are -enabled. Those features are listed here.

- -

C++ exceptions

- -

Use __has_feature(cxx_exceptions) to determine if C++ exceptions have been enabled. For -example, compiling code with -fexceptions enables C++ exceptions.

- -

C++ RTTI

- -

Use __has_feature(cxx_rtti) to determine if C++ RTTI has been enabled. For example, -compiling code with -fno-rtti disables the use of RTTI.

- - -

Checks for Upcoming Standard Language Features

- - -

The __has_feature macro can be used to query if certain upcoming -standard language features are enabled. Those features are listed here.

- -

Currently, all features listed here are slated for inclusion in the upcoming -C++0x standard. As a result, all the features that clang supports are enabled -with the -std=c++0x option when compiling C++ code. Features that are -not yet implemented will be noted.

- -

C++0x decltype()

- -

Use __has_feature(cxx_decltype) to determine if support for the -decltype() specifier is enabled.

- -

C++0x attributes

- -

Use __has_feature(cxx_attributes) to determine if support for -attribute parsing with C++0x's square bracket notation is enabled. - -

C++0x deleted functions

- -

Use __has_feature(cxx_deleted_functions) to determine if support for -deleted function definitions (with = delete) is enabled. - -

C++ TR concepts

- -

Use __has_feature(cxx_concepts) to determine if support for -concepts is enabled. clang does not currently implement this feature. - -

C++0x lambdas

- -

Use __has_feature(cxx_lambdas) to determine if support for -lambdas is enabled. clang does not currently implement this feature. - -

C++0x nullptr

- -

Use __has_feature(cxx_nullptr) to determine if support for -nullptr is enabled. clang does not yet fully implement this feature. - -

C++0x rvalue references

- -

Use __has_feature(cxx_rvalue_references) to determine if support for -rvalue references is enabled. clang does not yet fully implement this feature. - -

C++0x static_assert()

- -

Use __has_feature(cxx_static_assert) to determine if support for -compile-time assertions using static_assert is enabled.

- -

C++0x type inference

- -

Use __has_feature(cxx_auto_type) to determine C++0x type inference -is supported using the auto specifier. If this is disabled, -auto will instead be a storage class specifier, as in C or C++98.

- -

C++0x variadic templates

- -

Use __has_feature(cxx_variadic_templates) to determine if support -for templates taking any number of arguments with the ellipsis notation is -enabled. clang does not yet fully implement this feature.

- - -

Blocks

- - -

The syntax and high level language feature description is in BlockLanguageSpec.txt. Implementation and ABI -details for the clang implementation are in Block-ABI-Apple.txt.

- - -

Query for this feature with __has_feature(blocks).

- - -

Function Overloading in C

- - -

Clang provides support for C++ function overloading in C. Function -overloading in C is introduced using the overloadable attribute. For -example, one might provide several overloaded versions of a tgsin -function that invokes the appropriate standard function computing the sine of a -value with float, double, or long double -precision:

- -
-
-#include <math.h>
-float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
-double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
-long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
-
-
- -

Given these declarations, one can call tgsin with a -float value to receive a float result, with a -double to receive a double result, etc. Function -overloading in C follows the rules of C++ function overloading to pick -the best overload given the call arguments, with a few C-specific -semantics:

-
    -
  • Conversion from float or double to long - double is ranked as a floating-point promotion (per C99) rather - than as a floating-point conversion (as in C++).
    • - -
  • A conversion from a pointer of type T* to a pointer of type - U* is considered a pointer conversion (with conversion - rank) if T and U are compatible types.
    • - -
  • A conversion from type T to a value of type U - is permitted if T and U are compatible types. This - conversion is given "conversion" rank.
    • -
- -

The declaration of overloadable functions is restricted to -function declarations and definitions. Most importantly, if any -function with a given name is given the overloadable -attribute, then all function declarations and definitions with that -name (and in that scope) must have the overloadable -attribute. This rule even applies to redeclarations of functions whose original -declaration had the overloadable attribute, e.g.,

- -
-
-int f(int) __attribute__((overloadable));
-float f(float); // error: declaration of "f" must have the "overloadable" attribute
-
-int g(int) __attribute__((overloadable));
-int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
-
-
- -

Functions marked overloadable must have -prototypes. Therefore, the following code is ill-formed:

- -
-
-int h() __attribute__((overloadable)); // error: h does not have a prototype
-
-
- -

However, overloadable functions are allowed to use a -ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the unavailable attribute:

- -
-
-void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
-
-
- -

Functions declared with the overloadable attribute have -their names mangled according to the same rules as C++ function -names. For example, the three tgsin functions in our -motivating example get the mangled names _Z5tgsinf, -_Z5tgsind, and Z5tgsine, respectively. There are two -caveats to this use of name mangling:

- -
    - -
  • Future versions of Clang may change the name mangling of - functions overloaded in C, so you should not depend on an specific - mangling. To be completely safe, we strongly urge the use of - static inline with overloadable functions.
    • - -
  • The overloadable attribute has almost no meaning when - used in C++, because names will already be mangled and functions are - already overloadable. However, when an overloadable - function occurs within an extern "C" linkage specification, - it's name will be mangled in the same way as it would in - C.
    • -
- -

Query for this feature with __has_feature(attribute_overloadable).

- - - -

Builtin Functions

- - -

Clang supports a number of builtin library functions with the same syntax as -GCC, including things like __builtin_nan, -__builtin_constant_p, __builtin_choose_expr, -__builtin_types_compatible_p, __sync_fetch_and_add, etc. In -addition to the GCC builtins, Clang supports a number of builtins that GCC does -not, which are listed here.

- -

Please note that Clang does not and will not support all of the GCC builtins -for vector operations. Instead of using builtins, you should use the functions -defined in target-specific header files like <xmmintrin.h>, which -define portable wrappers for these. Many of the Clang versions of these -functions are implemented directly in terms of extended -vector support instead of builtins, in order to reduce the number of -builtins that we need to implement.

- - -

__builtin_shufflevector

- - -

__builtin_shufflevector is used to express generic vector -permutation/shuffle/swizzle operations. This builtin is also very important for -the implementation of various target-specific header files like -<xmmintrin.h>. -

- -

Syntax:

- -
-__builtin_shufflevector(vec1, vec2, index1, index2, ...)
-
- -

Examples:

- -
-  // Identity operation - return 4-element vector V1.
-  __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
-
-  // "Splat" element 0 of V1 into a 4-element result.
-  __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
-
-  // Reverse 4-element vector V1.
-  __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
-
-  // Concatenate every other element of 4-element vectors V1 and V2.
-  __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
-
-  // Concatenate every other element of 8-element vectors V1 and V2.
-  __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
-
- -

Description:

- -

The first two arguments to __builtin_shufflevector are vectors that have the -same element type. The remaining arguments are a list of integers that specify -the elements indices of the first two vectors that should be extracted and -returned in a new vector. These element indices are numbered sequentially -starting with the first vector, continuing into the second vector. Thus, if -vec1 is a 4-element vector, index 5 would refer to the second element of vec2. -

- -

The result of __builtin_shufflevector is a vector -with the same element type as vec1/vec2 but that has an element count equal to -the number of indices specified. -

- -

Query for this feature with __has_builtin(__builtin_shufflevector).

- - -

__builtin_unreachable

- - -

__builtin_unreachable is used to indicate that a specific point in -the program cannot be reached, even if the compiler might otherwise think it -can. This is useful to improve optimization and eliminates certain warnings. -For example, without the __builtin_unreachable in the example below, -the compiler assumes that the inline asm can fall through and prints a "function -declared 'noreturn' should not return" warning. -

- -

Syntax:

- -
-__builtin_unreachable()
-
- -

Example of Use:

- -
-void myabort(void) __attribute__((noreturn));
-void myabort(void) {
-    asm("int3");
-    __builtin_unreachable();
-}
-
- -

Description:

- -

The __builtin_unreachable() builtin has completely undefined behavior. Since -it has undefined behavior, it is a statement that it is never reached and the -optimizer can take advantage of this to produce better code. This builtin takes -no arguments and produces a void result. -

- -

Query for this feature with __has_builtin(__builtin_unreachable).

- - - -

Target-Specific Extensions

- - -

Clang supports some language features conditionally on some targets.

- - -

X86/X86-64 Language Extensions

- - -

The X86 backend has these language extensions:

- - -

Memory references off the GS segment

- - -

Annotating a pointer with address space #256 causes it to be code generated -relative to the X86 GS segment register, and address space #257 causes it to be -relative to the X86 FS segment. Note that this is a very very low-level -feature that should only be used if you know what you're doing (for example in -an OS kernel).

- -

Here is an example:

- -
-#define GS_RELATIVE __attribute__((address_space(256)))
-int foo(int GS_RELATIVE *P) {
-  return *P;
-}
-
- -

Which compiles to (on X86-32):

- -
-_foo:
-	movl	4(%esp), %eax
-	movl	%gs:(%eax), %eax
-	ret
-
- - -

Static Analysis-Specific Extensions

- - -

Clang supports additional attributes that are useful for documenting program -invariants and rules for static analysis tools. The extensions documented here -are used by the path-sensitive static analyzer -engine that is part of Clang's Analysis library.

- - -

Analyzer Attributes

- - -

analyzer_noreturn

- -

Clang's static analysis engine understands the standard noreturn -attribute. This attribute, which is typically affixed to a function prototype, -indicates that a call to a given function never returns. Function prototypes for -common functions like exit are typically annotated with this attribute, -as well as a variety of common assertion handlers. Users can educate the static -analyzer about their own custom assertion handles (thus cutting down on false -positives due to false paths) by marking their own "panic" functions -with this attribute.

- -

While useful, noreturn is not applicable in all cases. Sometimes -there are special functions that for all intents and purposes should be -considered panic functions (i.e., they are only called when an internal program -error occurs) but may actually return so that the program can fail gracefully. -The analyzer_noreturn attribute allows one to annotate such functions -as being interpreted as "no return" functions by the analyzer (thus -pruning bogus paths) but will not affect compilation (as in the case of -noreturn).

- -

Usage: The analyzer_noreturn attribute can be placed in the -same places where the noreturn attribute can be placed. It is commonly -placed at the end of function prototypes:

- -
-  void foo() __attribute__((analyzer_noreturn));
-
- -

Query for this feature with __has_feature(attribute_analyzer_noreturn).

- - -
- - diff --git a/docs/Makefile b/docs/Makefile index e9bbb28f68..98bcff3e8b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,91 +7,7 @@ # ##===----------------------------------------------------------------------===## -LEVEL := ../../.. -DIRS := tools - -ifdef BUILD_FOR_WEBSITE -PROJ_OBJ_DIR = . -DOXYGEN = doxygen - -$(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in - cat $< | sed \ - -e 's/@abs_top_srcdir@/../g' \ - -e 's/@DOT@/dot/g' \ - -e 's/@PACKAGE_VERSION@/mainline/' \ - -e 's/@abs_top_builddir@/../g' > $@ -endif +LEVEL = ../../.. +DIRS = main api include $(LEVEL)/Makefile.common - -HTML := $(wildcard $(PROJ_SRC_DIR)/*.html) \ - $(wildcard $(PROJ_SRC_DIR)/*.css) -#IMAGES := $(wildcard $(PROJ_SRC_DIR)/img/*.*) -DOXYFILES := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \ - doxygen.intro -EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide img - -.PHONY: install-html install-doxygen doxygen generated - -install_targets := -ifndef ONLY_MAN_DOCS -install_targets += install-html -endif -ifeq ($(ENABLE_DOXYGEN),1) -install_targets += install-doxygen -endif -install-local:: $(install_targets) - -# Live documentation is generated for the web site using this target: -# 'make generated BUILD_FOR_WEBSITE=1' -generated:: doxygen - -install-html: $(PROJ_OBJ_DIR)/html.tar.gz - $(Echo) Installing HTML documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/img - $(Verb) $(DataInstall) $(HTML) $(DESTDIR)$(PROJ_docsdir)/html -# $(Verb) $(DataInstall) $(IMAGES) $(DESTDIR)$(PROJ_docsdir)/html/img - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(DESTDIR)$(PROJ_docsdir) - -$(PROJ_OBJ_DIR)/html.tar.gz: $(HTML) - $(Echo) Packaging HTML documentation - $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar - $(Verb) cd $(PROJ_SRC_DIR) && \ - $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html - $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/html.tar - -install-doxygen: doxygen - $(Echo) Installing doxygen documentation - $(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/doxygen - $(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(DESTDIR)$(PROJ_docsdir) - $(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \ - $(FIND) . -type f -exec \ - $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/html/doxygen \; - -doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz - -regendoc: - $(Echo) Building doxygen documentation - $(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \ - $(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \ - fi - $(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg - -$(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg - $(Echo) Packaging doxygen documentation - $(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar - $(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen - $(Verb) $(GZIP) $(PROJ_OBJ_DIR)/doxygen.tar - $(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/ - -userloc: $(LLVM_SRC_ROOT)/docs/userloc.html - -$(LLVM_SRC_ROOT)/docs/userloc.html: - $(Echo) Making User LOC Table - $(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \ - -html lib include tools runtime utils examples autoconf test > docs/userloc.html - -uninstall-local:: - $(Echo) Uninstalling Documentation - $(Verb) $(RM) -rf $(DESTDIR)$(PROJ_docsdir) diff --git a/docs/PCHInternals.html b/docs/PCHInternals.html deleted file mode 100644 index e21ec5e90d..0000000000 --- a/docs/PCHInternals.html +++ /dev/null @@ -1,500 +0,0 @@ - - - Precompiled Headers (PCH) - - - - - - - - - -
- -

Precompiled Headers

- -

This document describes the design and implementation of Clang's - precompiled headers (PCH). If you are interested in the end-user - view, please see the User's Manual.

- -

Table of Contents

- - -

Using Precompiled Headers with clang

- -

The Clang compiler frontend, clang -cc1, supports two command line -options for generating and using PCH files.

- -

To generate PCH files using clang -cc1, use the option --emit-pch: - -

 $ clang -cc1 test.h -emit-pch -o test.h.pch
- -

This option is transparently used by clang when generating -PCH files. The resulting PCH file contains the serialized form of the -compiler's internal representation after it has completed parsing and -semantic analysis. The PCH file can then be used as a prefix header -with the -include-pch option:

- -
-  $ clang -cc1 -include-pch test.h.pch test.c -o test.s
-
- -

Design Philosophy

- -

Precompiled headers are meant to improve overall compile times for - projects, so the design of precompiled headers is entirely driven by - performance concerns. The use case for precompiled headers is - relatively simple: when there is a common set of headers that is - included in nearly every source file in the project, we - precompile that bundle of headers into a single precompiled - header (PCH file). Then, when compiling the source files in the - project, we load the PCH file first (as a prefix header), which acts - as a stand-in for that bundle of headers.

- -

A precompiled header implementation improves performance when:

-
    -
  • Loading the PCH file is significantly faster than re-parsing the - bundle of headers stored within the PCH file. Thus, a precompiled - header design attempts to minimize the cost of reading the PCH - file. Ideally, this cost should not vary with the size of the - precompiled header file.
    • - -
  • The cost of generating the PCH file initially is not so large - that it counters the per-source-file performance improvement due to - eliminating the need to parse the bundled headers in the first - place. This is particularly important on multi-core systems, because - PCH file generation serializes the build when all compilations - require the PCH file to be up-to-date.
    • -
- -

Clang's precompiled headers are designed with a compact on-disk -representation, which minimizes both PCH creation time and the time -required to initially load the PCH file. The PCH file itself contains -a serialized representation of Clang's abstract syntax trees and -supporting data structures, stored using the same compressed bitstream -as LLVM's bitcode -file format.

- -

Clang's precompiled headers are loaded "lazily" from disk. When a -PCH file is initially loaded, Clang reads only a small amount of data -from the PCH file to establish where certain important data structures -are stored. The amount of data read in this initial load is -independent of the size of the PCH file, such that a larger PCH file -does not lead to longer PCH load times. The actual header data in the -PCH file--macros, functions, variables, types, etc.--is loaded only -when it is referenced from the user's code, at which point only that -entity (and those entities it depends on) are deserialized from the -PCH file. With this approach, the cost of using a precompiled header -for a translation unit is proportional to the amount of code actually -used from the header, rather than being proportional to the size of -the header itself.

- -

When given the -print-stats option, Clang produces -statistics describing how much of the precompiled header was actually -loaded from disk. For a simple "Hello, World!" program that includes -the Apple Cocoa.h header (which is built as a precompiled -header), this option illustrates how little of the actual precompiled -header is required:

- -
-*** PCH Statistics:
-  933 stat cache hits
-  4 stat cache misses
-  895/39981 source location entries read (2.238563%)
-  19/15315 types read (0.124061%)
-  20/82685 declarations read (0.024188%)
-  154/58070 identifiers read (0.265197%)
-  0/7260 selectors read (0.000000%)
-  0/30842 statements read (0.000000%)
-  4/8400 macros read (0.047619%)
-  1/4995 lexical declcontexts read (0.020020%)
-  0/4413 visible declcontexts read (0.000000%)
-  0/7230 method pool entries read (0.000000%)
-  0 method pool misses
-
- -

For this small program, only a tiny fraction of the source -locations, types, declarations, identifiers, and macros were actually -deserialized from the precompiled header. These statistics can be -useful to determine whether the precompiled header implementation can -be improved by making more of the implementation lazy.

- -

Precompiled Header Contents

- -Precompiled header layout - -

Clang's precompiled headers are organized into several different -blocks, each of which contains the serialized representation of a part -of Clang's internal representation. Each of the blocks corresponds to -either a block or a record within LLVM's bitstream -format. The contents of each of these logical blocks are described -below.

- -

For a given precompiled header, the llvm-bcanalyzer -utility can be used to examine the actual structure of the bitstream -for the precompiled header. This information can be used both to help -understand the structure of the precompiled header and to isolate -areas where precompiled headers can still be optimized, e.g., through -the introduction of abbreviations.

- -

Metadata Block

- -

The metadata block contains several records that provide -information about how the precompiled header was built. This metadata -is primarily used to validate the use of a precompiled header. For -example, a precompiled header built for a 32-bit x86 target cannot be used -when compiling for a 64-bit x86 target. The metadata block contains -information about:

- -
-
Language options
-
Describes the particular language dialect used to compile the -PCH file, including major options (e.g., Objective-C support) and more -minor options (e.g., support for "//" comments). The contents of this -record correspond to the LangOptions class.
- -
Target architecture
-
The target triple that describes the architecture, platform, and -ABI for which the PCH file was generated, e.g., -i386-apple-darwin9.
- -
PCH version
-
The major and minor version numbers of the precompiled header -format. Changes in the minor version number should not affect backward -compatibility, while changes in the major version number imply that a -newer compiler cannot read an older precompiled header (and -vice-versa).
- -
Original file name
-
The full path of the header that was used to generate the -precompiled header.
- -
Predefines buffer
-
Although not explicitly stored as part of the metadata, the -predefines buffer is used in the validation of the precompiled header. -The predefines buffer itself contains code generated by the compiler -to initialize the preprocessor state according to the current target, -platform, and command-line options. For example, the predefines buffer -will contain "#define __STDC__ 1" when we are compiling C -without Microsoft extensions. The predefines buffer itself is stored -within the source manager block, but its -contents are verified along with the rest of the metadata.
- -
- -

Source Manager Block

- -

The source manager block contains the serialized representation of -Clang's SourceManager class, -which handles the mapping from source locations (as represented in -Clang's abstract syntax tree) into actual column/line positions within -a source file or macro instantiation. The precompiled header's -representation of the source manager also includes information about -all of the headers that were (transitively) included when building the -precompiled header.

- -

The bulk of the source manager block is dedicated to information -about the various files, buffers, and macro instantiations into which -a source location can refer. Each of these is referenced by a numeric -"file ID", which is a unique number (allocated starting at 1) stored -in the source location. Clang serializes the information for each kind -of file ID, along with an index that maps file IDs to the position -within the PCH file where the information about that file ID is -stored. The data associated with a file ID is loaded only when -required by the front end, e.g., to emit a diagnostic that includes a -macro instantiation history inside the header itself.

- -

The source manager block also contains information about all of the -headers that were included when building the precompiled header. This -includes information about the controlling macro for the header (e.g., -when the preprocessor identified that the contents of the header -dependent on a macro like LLVM_CLANG_SOURCEMANAGER_H) -along with a cached version of the results of the stat() -system calls performed when building the precompiled header. The -latter is particularly useful in reducing system time when searching -for include files.

- -

Preprocessor Block

- -

The preprocessor block contains the serialized representation of -the preprocessor. Specifically, it contains all of the macros that -have been defined by the end of the header used to build the -precompiled header, along with the token sequences that comprise each -macro. The macro definitions are only read from the PCH file when the -name of the macro first occurs in the program. This lazy loading of -macro definitions is triggered by lookups into the identifier table.

- -

Types Block

- -

The types block contains the serialized representation of all of -the types referenced in the translation unit. Each Clang type node -(PointerType, FunctionProtoType, etc.) has a -corresponding record type in the PCH file. When types are deserialized -from the precompiled header, the data within the record is used to -reconstruct the appropriate type node using the AST context.

- -

Each type has a unique type ID, which is an integer that uniquely -identifies that type. Type ID 0 represents the NULL type, type IDs -less than NUM_PREDEF_TYPE_IDS represent predefined types -(void, float, etc.), while other -"user-defined" type IDs are assigned consecutively from -NUM_PREDEF_TYPE_IDS upward as the types are encountered. -The PCH file has an associated mapping from the user-defined types -block to the location within the types block where the serialized -representation of that type resides, enabling lazy deserialization of -types. When a type is referenced from within the PCH file, that -reference is encoded using the type ID shifted left by 3 bits. The -lower three bits are used to represent the const, -volatile, and restrict qualifiers, as in -Clang's QualType -class.

- -

Declarations Block

- -

The declarations block contains the serialized representation of -all of the declarations referenced in the translation unit. Each Clang -declaration node (VarDecl, FunctionDecl, -etc.) has a corresponding record type in the PCH file. When -declarations are deserialized from the precompiled header, the data -within the record is used to build and populate a new instance of the -corresponding Decl node. As with types, each declaration -node has a numeric ID that is used to refer to that declaration within -the PCH file. In addition, a lookup table provides a mapping from that -numeric ID to the offset within the precompiled header where that -declaration is described.

- -

Declarations in Clang's abstract syntax trees are stored -hierarchically. At the top of the hierarchy is the translation unit -(TranslationUnitDecl), which contains all of the -declarations in the translation unit. These declarations (such as -functions or struct types) may also contain other declarations inside -them, and so on. Within Clang, each declaration is stored within a declaration -context, as represented by the DeclContext class. -Declaration contexts provide the mechanism to perform name lookup -within a given declaration (e.g., find the member named x -in a structure) and iterate over the declarations stored within a -context (e.g., iterate over all of the fields of a structure for -structure layout).

- -

In Clang's precompiled header format, deserializing a declaration -that is a DeclContext is a separate operation from -deserializing all of the declarations stored within that declaration -context. Therefore, Clang will deserialize the translation unit -declaration without deserializing the declarations within that -translation unit. When required, the declarations stored within a -declaration context will be deserialized. There are two representations -of the declarations within a declaration context, which correspond to -the name-lookup and iteration behavior described above:

- -
    -
  • When the front end performs name lookup to find a name - x within a given declaration context (for example, - during semantic analysis of the expression p->x, - where p's type is defined in the precompiled header), - Clang deserializes a hash table mapping from the names within that - declaration context to the declaration IDs that represent each - visible declaration with that name. The entire hash table is - deserialized at this point (into the llvm::DenseMap - stored within each DeclContext object), but the actual - declarations are not yet deserialized. In a second step, those - declarations with the name x will be deserialized and - will be used as the result of name lookup.
    • - -
  • When the front end performs iteration over all of the - declarations within a declaration context, all of those declarations - are immediately de-serialized. For large declaration contexts (e.g., - the translation unit), this operation is expensive; however, large - declaration contexts are not traversed in normal compilation, since - such a traversal is unnecessary. However, it is common for the code - generator and semantic analysis to traverse declaration contexts for - structs, classes, unions, and enumerations, although those contexts - contain relatively few declarations in the common case.
    • -
- -

Statements and Expressions

- -

Statements and expressions are stored in the precompiled header in -both the types and the declarations blocks, because every statement or -expression will be associated with either a type or declaration. The -actual statement and expression records are stored immediately -following the declaration or type that owns the statement or -expression. For example, the statement representing the body of a -function will be stored directly following the declaration of the -function.

- -

As with types and declarations, each statement and expression kind -in Clang's abstract syntax tree (ForStmt, -CallExpr, etc.) has a corresponding record type in the -precompiled header, which contains the serialized representation of -that statement or expression. Each substatement or subexpression -within an expression is stored as a separate record (which keeps most -records to a fixed size). Within the precompiled header, the -subexpressions of an expression are stored prior to the expression -that owns those expression, using a form of Reverse -Polish Notation. For example, an expression 3 - 4 + 5 -would be represented as follows:

- - - - - - - - -
IntegerLiteral(3)
IntegerLiteral(4)
BinaryOperator(-)
IntegerLiteral(5)
BinaryOperator(+)
STOP
- -

When reading this representation, Clang evaluates each expression -record it encounters, builds the appropriate abstract synax tree node, -and then pushes that expression on to a stack. When a record contains N -subexpressions--BinaryOperator has two of them--those -expressions are popped from the top of the stack. The special STOP -code indicates that we have reached the end of a serialized expression -or statement; other expression or statement records may follow, but -they are part of a different expression.

- -

Identifier Table Block

- -

The identifier table block contains an on-disk hash table that maps -each identifier mentioned within the precompiled header to the -serialized representation of the identifier's information (e.g, the -IdentifierInfo structure). The serialized representation -contains:

- -
    -
  • The actual identifier string.
    • -
  • Flags that describe whether this identifier is the name of a - built-in, a poisoned identifier, an extension token, or a - macro.
    • -
  • If the identifier names a macro, the offset of the macro - definition within the preprocessor - block.
    • -
  • If the identifier names one or more declarations visible from - translation unit scope, the declaration IDs of these - declarations.
    • -
- -

When a precompiled header is loaded, the precompiled header -mechanism introduces itself into the identifier table as an external -lookup source. Thus, when the user program refers to an identifier -that has not yet been seen, Clang will perform a lookup into the -identifier table. If an identifier is found, its contents (macro -definitions, flags, top-level declarations, etc.) will be deserialized, at which point the corresponding IdentifierInfo structure will have the same contents it would have after parsing the headers in the precompiled header.

- -

Within the PCH file, the identifiers used to name declarations are represented with an integral value. A separate table provides a mapping from this integral value (the identifier ID) to the location within the on-disk -hash table where that identifier is stored. This mapping is used when -deserializing the name of a declaration, the identifier of a token, or -any other construct in the PCH file that refers to a name.

- -

Method Pool Block

- -

The method pool block is represented as an on-disk hash table that -serves two purposes: it provides a mapping from the names of -Objective-C selectors to the set of Objective-C instance and class -methods that have that particular selector (which is required for -semantic analysis in Objective-C) and also stores all of the selectors -used by entities within the precompiled header. The design of the -method pool is similar to that of the identifier -table: the first time a particular selector is formed during the -compilation of the program, Clang will search in the on-disk hash -table of selectors; if found, Clang will read the Objective-C methods -associated with that selector into the appropriate front-end data -structure (Sema::InstanceMethodPool and -Sema::FactoryMethodPool for instance and class methods, -respectively).

- -

As with identifiers, selectors are represented by numeric values -within the PCH file. A separate index maps these numeric selector -values to the offset of the selector within the on-disk hash table, -and will be used when de-serializing an Objective-C method declaration -(or other Objective-C construct) that refers to the selector.

- -

Precompiled Header Integration Points

- -

The "lazy" deserialization behavior of precompiled headers requires -their integration into several completely different submodules of -Clang. For example, lazily deserializing the declarations during name -lookup requires that the name-lookup routines be able to query the -precompiled header to find entities within the PCH file.

- -

For each Clang data structure that requires direct interaction with -the precompiled header logic, there is an abstract class that provides -the interface between the two modules. The PCHReader -class, which handles the loading of a precompiled header, inherits -from all of these abstract classes to provide lazy deserialization of -Clang's data structures. PCHReader implements the -following abstract classes:

- -
-
StatSysCallCache
-
This abstract interface is associated with the - FileManager class, and is used whenever the file - manager is going to perform a stat() system call.
- -
ExternalSLocEntrySource
-
This abstract interface is associated with the - SourceManager class, and is used whenever the - source manager needs to load the details - of a file, buffer, or macro instantiation.
- -
IdentifierInfoLookup
-
This abstract interface is associated with the - IdentifierTable class, and is used whenever the - program source refers to an identifier that has not yet been seen. - In this case, the precompiled header implementation searches for - this identifier within its identifier table - to load any top-level declarations or macros associated with that - identifier.
- -
ExternalASTSource
-
This abstract interface is associated with the - ASTContext class, and is used whenever the abstract - syntax tree nodes need to loaded from the precompiled header. It - provides the ability to de-serialize declarations and types - identified by their numeric values, read the bodies of functions - when required, and read the declarations stored within a - declaration context (either for iteration or for name lookup).
- -
ExternalSemaSource
-
This abstract interface is associated with the Sema - class, and is used whenever semantic analysis needs to read - information from the global method - pool.
-
- -
- - - diff --git a/docs/PCHLayout.graffle b/docs/PCHLayout.graffle deleted file mode 100644 index 5c96bfb701..0000000000 --- a/docs/PCHLayout.graffle +++ /dev/null @@ -1,1880 +0,0 @@ - - - - - ActiveLayerIndex - 0 - ApplicationVersion - - com.omnigroup.OmniGrafflePro - 137.11.0.108132 - - AutoAdjust - - BackgroundGraphic - - Bounds - {{0, 0}, {576, 733}} - Class - SolidGraphic - ID - 2 - Style - - shadow - - Draws - NO - - stroke - - Draws - NO - - - - CanvasOrigin - {0, 0} - ColumnAlign - 1 - ColumnSpacing - 36 - CreationDate - 2009-06-02 11:19:43 -0700 - Creator - Douglas Gregor - DisplayScale - 1 0/72 in = 1.0000 in - GraphDocumentVersion - 6 - GraphicsList - - - Bounds - {{35, 301}, {104, 30}} - Class - ShapedGraphic - ID - 13 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 0.175793 - g - 0.402929 - r - 1 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Method Pool} - - - - Bounds - {{32, 58}, {110, 14}} - Class - ShapedGraphic - FitText - YES - Flow - Resize - ID - 12 - Layer - 0 - Shape - Rectangle - Style - - fill - - Draws - NO - - shadow - - Draws - NO - - stroke - - Draws - NO - - - Text - - Pad - 0 - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Precompiled Header} - VerticalPad - 0 - - Wrap - NO - - - Bounds - {{35, 190}, {104, 30}} - Class - ShapedGraphic - ID - 11 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 1 - g - 0.796208 - r - 0.324589 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Types} - - - - Bounds - {{35, 227}, {104, 30}} - Class - ShapedGraphic - ID - 10 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 1 - g - 0.382716 - r - 0.524072 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Declarations} - - - - Bounds - {{35, 264}, {104, 30}} - Class - ShapedGraphic - ID - 8 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 0.99938 - g - 0.457913 - r - 1 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Identifier Table} - - - - Bounds - {{35, 153}, {104, 30}} - Class - ShapedGraphic - ID - 7 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 0.669993 - g - 1 - r - 0.254644 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Preprocessor} - - - - Bounds - {{35, 116}, {104, 30}} - Class - ShapedGraphic - ID - 6 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 0.258332 - g - 1 - r - 0.593784 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Source Manager} - - - - Bounds - {{35, 79}, {104, 30}} - Class - ShapedGraphic - ID - 5 - Layer - 0 - Shape - Rectangle - Style - - fill - - Color - - b - 0.270873 - g - 1 - r - 0.979351 - - - stroke - - CornerRadius - 9 - - - Text - - Text - {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 -{\fonttbl\f0\fswiss\fcharset0 Helvetica;} -{\colortbl;\red255\green255\blue255;} -\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural - -\f0\fs24 \cf0 Metadata} - - - - Bounds - {{21, 47}, {132, 293}} - Class - ShapedGraphic - ID - 4 - Layer - 1 - Shape - Rectangle - Style - - fill - - FillType - 2 - GradientAngle - 90 - - stroke - - CornerRadius - 9 - - - - - GridInfo - - GuidesLocked - NO - GuidesVisible - YES - HPages - 1 - ImageCounter - 1 - KeepToScale - - Layers - - - Lock - NO - Name - Sub-blocks - Print - YES - View - YES - - - Lock - NO - Name - PCH Block - Print - YES - View - YES - - - LayoutInfo - - Animate - NO - circoMinDist - 18 - circoSeparation - 0.0 - layoutEngine - dot - neatoSeparation - 0.0 - twopiSeparation - 0.0 - - LinksVisible - NO - MagnetsVisible - NO - MasterSheets - - ModificationDate - 2009-06-03 08:22:05 -0700 - Modifier - Douglas Gregor - NotesVisible - NO - Orientation - 2 - OriginVisible - NO - PageBreaks - YES - PrintInfo - - NSBottomMargin - - float - 41 - - NSLeftMargin - - float - 18 - - NSPaperSize - - size - {612, 792} - - NSRightMargin - - float - 18 - - NSTopMargin - - float - 18 - - - PrintOnePage - - QuickLookPreview - - JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aCA1IDAgUiAvRmls - dGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAGNWNtuGzcQfedX8LF5iMz77r7WadEU - CJDUBvqsyptagWQ5klOgP9tv6TnDy64syXYMhGeo5XAuZ4bc/a6/6O/a4C92SXfe6/2o - /9QP2iySkX96ra+uD1avDtrK32Gl35tFLL9OqChQUPBVX30e96vx8enHcqP3a2xhY5Bt - vI3aGu27Xq+2+urj1uoPOxhBM7zRqU96q20IRGoD1C+GziT5wUaP0eYJEbpOr6Da62Cc - xtNAfugWxg1hWuoHr6gRI57GJgQb7aI8l+ednRYCU91KF3A0KEybxcB/OmF76GliNa1o - prFJu6E+DWGl75uXimHG4oidHf63CD7tLgk4jaDE773VfaejH7CCAby5t/pwr3IAz+TR - 6t+RtW+n+by+EX1G31wzPVW5IQkUNCNOoSu5AJilAhIDHa3Ez2WBvkn4va2J8FEyhdiX - HPpgJLUccyIA5omAyESUhRmDeRU4qzzUyyMyXSMf0zwPzbCWB1jc0gCcs6CAtvoGzDsN - tUsSj+i0AxPNULjqMlcRrqMHYucYMZDZX3jA52R93IbzDwRskzVEJeXwfIuQ4LBskS5o - GGpBdecf8H1XjOzzA1d/jJvl0/qf8Xq32e3X2/Fpv16xWGu5I7rd4COqFexYuM70HUiB - 8g9BJZQz6pQVCwRy+FDqFKL1qI0A3rNwswD/MwLJ+TQecL3wR01LEQTRyGBgEzxC1aA6 - 6zmLCGRdqImhDkzKwEdF+Wg6RGrA79WcSRsMpVIM5EOBW/Suc9WAn7uheAwwcxgS3el9 - rQYKyIXMWkOC83drcoAmdy1oRXc5irsEM3cpwvK6MGMpHE6ii0WVB5EkCthXvG3GNG9h - ZXah+CrOCPevD2h1ByWJNWj2M+/RaBJMB+9+vgXlS4tw+j0Ly6akg74FJ39FIwBFbr/q - nz6NT8u75dPynbr9pn+5RW2dO0fQ8wYcAOwGJFbsvXeFWDpZaTokFtAUZ0VReGPdjFim - RjoO7AF8IA65MUEonIxwhJHmKOwlmEWaIiLdFgpmQyvgeMh8w8YMNcwq5rRQ01CyCUMl - FuA5YjGyeNJaOfO8UUSTy/KDcAenRD7SSCRXa8n6HCDMhXooFpfRc1l5CDDGTC6Amcuc - h1ttITHUiW8ERSbH2jQ2FnbZak5zmXYXR4rL2acZwbRR6BxnCMaT9oRgISx87FGgzwl2 - s/uBe4X+tHxY/j3uX6OZiyGFQrOUcGQjItK/QAVTqploirmiKCzq8ulVBB43Mh1z8YNm - MdSkVJpFLgXNMGaaAcxiznlSqS4UzNov4HjI0x1PU2QhVnNazGkoYs6hxJzwJZrhzJaW - rXhOTy7LsS00i/XmRJol3oBkussNHnNdOchrZSnbe3GZY6YZwMxlzsOttlAwG24BbVAW - u+RpbJxpVs1pLtNu0gxDpZn49AaaxSQn8LM+hotG6s25RvZ5Pz7ud6vxcNi9wjK2sBC7 - gZmX+4jv0Zwzy0KqZwbRFHJFkbEFPadmFhJTKdOB3SWjfK5AKE8GJgd7cRSWEcxCThFh - DaEsFMwuWcDxkKexsbCsmdNCTkMRcg4l5IQvsMylcjFQRJPLmiI9cimf+1nomEqZ7tld - Mmo3h+yykts8XOYoLCOYuUwRbrm+LBTMLllAG5TDLnkaGwvLmjnNZRoKlzkUlwnLTTGf - lpeaWeBl4qSZeVSN7QacCs+72ce78eFp/d/Uxo4P3wvqFjGhFZ8oG/f6nb79puTYfYMi - i6PXG1yCTzTdUg+Ob7xVvEVPuqRn+ddmnFRduAm4YDqc/mbhe9dZMBHvM5LkiMtjvmIS - TUxSFEmUaNqpB5IivqV4GpNC387NWjx4yZXiwZiLB2DGpAARbGkLBRfKBOgt8tE0Npbi - aeY0JtFQtmgMtUUDvlQ8rlx+lAOaXNYUpTZ8u9ugkjz1ynTrFy6221EtnpgvPw5jLh6A - mcuchz9tITHU5SoBKDLOoGkaG+fiqeY0l2koiwdDLR7AtxXPIK84z1u0X/jQJzT+58Xz - YVxtlnu8weweDlMFnWeZdyH2A1nWDckZnvGVZaGcijoCTSFXFIVlLN/6IhM9m4JMO/ng - QBradmwWlkWbT0WOwjKCWcgpIqxtITHUScgJinw0jY0zy6o5LeQ0lCzDUFkG+ALLLAJR - LgJAk8uaP9A3O7SrDQW2fmGZlVd79nDbLkeVZShhFpbDmFkGMHOZ8/CnLRTMS1UBbVAO - u8g0NxaWNXOayzQULnMoLmef3nIRcOD2SYu2CS80BleQE5ZJLzzXU+NZRcPC+zTYM4r+ - fRwPl/pzSueMwj0xDQGJPzEKt5PVbvu43ox3+rdxeffaTVjuKHiDcAiYWdgO1xXkqtxR - vMtswI0iU7qklCLTHlw3FUBw9cAOjQ3BIHr5jC4FwM9n0mblMxo+F+TPcy1/FJHxtpC4 - pp2gyEfT2FgKoJkzaYOhYAPtLWwgfKEAvLGlAIhmBUCRLnuTvw1mAR9AcgH4VvPepRqT - Ei1+mKLLHKUACGYFQBH+tIWCS81Tb5HRZilJAXhsLAXQzGku01C4zKG4TPi2Nsv30pMC - 8B434R7t/oRreKW/393pz7vdZuqyX/4HnD2NIAplbmRzdHJlYW0KZW5kb2JqCjUgMCBv - YmoKMTkzOQplbmRvYmoKMiAwIG9iago8PCAvVHlwZSAvUGFnZSAvUGFyZW50IDMgMCBS - IC9SZXNvdXJjZXMgNiAwIFIgL0NvbnRlbnRzIDQgMCBSIC9NZWRpYUJveCBbMCAwIDU3 - NiA3MzNdCj4+CmVuZG9iago2IDAgb2JqCjw8IC9Qcm9jU2V0IFsgL1BERiAvVGV4dCAv - SW1hZ2VCIC9JbWFnZUMgL0ltYWdlSSBdIC9Db2xvclNwYWNlIDw8IC9DczIgMjUgMCBS - Ci9DczEgNyAwIFIgPj4gL0ZvbnQgPDwgL0YxLjAgMjYgMCBSID4+IC9YT2JqZWN0IDw8 - IC9JbTEgOCAwIFIgL0ltMiAxMSAwIFIKL0ltMyAxMyAwIFIgL0ltNSAxNyAwIFIgL0lt - NyAyMSAwIFIgL0ltOCAyMyAwIFIgL0ltNCAxNSAwIFIgL0ltNiAxOSAwIFIgPj4KL1No - YWRpbmcgPDwgL1NoMSAxMCAwIFIgPj4gPj4KZW5kb2JqCjEwIDAgb2JqCjw8IC9Db2xv - clNwYWNlIDcgMCBSIC9TaGFkaW5nVHlwZSAyIC9Db29yZHMgWyA2Ni41IC0xNDcgNjYu - NDk5OTUgMTQ3IF0gL0RvbWFpbgpbIDAgMSBdIC9FeHRlbmQgWyBmYWxzZSBmYWxzZSBd - IC9GdW5jdGlvbiAyNyAwIFIgPj4KZW5kb2JqCjggMCBvYmoKPDwgL0xlbmd0aCA5IDAg - UiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dpZHRoIDMwOCAvSGVpZ2h0 - IDYzMCAvQ29sb3JTcGFjZQoyOCAwIFIgL1NNYXNrIDI5IDAgUiAvQml0c1BlckNvbXBv - bmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae3QMQEAAADCoPVP - bQlPiEBhwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGPgMDOJgAAEK - ZW5kc3RyZWFtCmVuZG9iago5IDAgb2JqCjI1NjIKZW5kb2JqCjExIDAgb2JqCjw8IC9M - ZW5ndGggMTIgMCBSIC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGgg - MjUyIC9IZWlnaHQgMTA0IC9Db2xvclNwYWNlCjMxIDAgUiAvU01hc2sgMzIgMCBSIC9C - aXRzUGVyQ29tcG9uZW50IDggL0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB - 7dABDQAAAMKg909tDjeIQGHAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED - BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED - BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - +B4YMy8AAQplbmRzdHJlYW0KZW5kb2JqCjEyIDAgb2JqCjM2NgplbmRvYmoKMTMgMCBv - YmoKPDwgL0xlbmd0aCAxNCAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdl - IC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKMzEgMCBSIC9TTWFzayAz - NCAwIFIgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+Pgpz - dHJlYW0KeAHt0AENAAAAwqD3T20ON4hAYcCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw - YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG - DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA - AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw - YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG - DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA - AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw - YMCAAQMGDBj4HhgzLwABCmVuZHN0cmVhbQplbmRvYmoKMTQgMCBvYmoKMzY2CmVuZG9i - agoxNyAwIG9iago8PCAvTGVuZ3RoIDE4IDAgUiAvVHlwZSAvWE9iamVjdCAvU3VidHlw - ZSAvSW1hZ2UgL1dpZHRoIDI1MiAvSGVpZ2h0IDEwNCAvQ29sb3JTcGFjZQozMSAwIFIg - L1NNYXNrIDM2IDAgUiAvQml0c1BlckNvbXBvbmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVj - b2RlID4+CnN0cmVhbQp4Ae3QAQ0AAADCoPdPbQ43iEBhwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGPgeGDMvAAEKZW5kc3RyZWFtCmVuZG9iagoxOCAwIG9iagoz - NjYKZW5kb2JqCjIxIDAgb2JqCjw8IC9MZW5ndGggMjIgMCBSIC9UeXBlIC9YT2JqZWN0 - IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggMjUyIC9IZWlnaHQgMTA0IC9Db2xvclNwYWNl - CjMxIDAgUiAvU01hc2sgMzggMCBSIC9CaXRzUGVyQ29tcG9uZW50IDggL0ZpbHRlciAv - RmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7dABDQAAAMKg909tDjeIQGHAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED - BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED - BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY+B4YMy8AAQplbmRzdHJlYW0KZW5kb2JqCjIy - IDAgb2JqCjM2NgplbmRvYmoKMjMgMCBvYmoKPDwgL0xlbmd0aCAyNCAwIFIgL1R5cGUg - L1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0Nv - bG9yU3BhY2UKMzEgMCBSIC9TTWFzayA0MCAwIFIgL0JpdHNQZXJDb21wb25lbnQgOCAv - RmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHt0AENAAAAwqD3T20ON4hAYcCA - AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw - YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG - DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA - AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw - YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG - DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA - AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBj4HhgzLwABCmVuZHN0cmVhbQpl - bmRvYmoKMjQgMCBvYmoKMzY2CmVuZG9iagoxNSAwIG9iago8PCAvTGVuZ3RoIDE2IDAg - UiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dpZHRoIDI1MiAvSGVpZ2h0 - IDEwNCAvQ29sb3JTcGFjZQozMSAwIFIgL1NNYXNrIDQyIDAgUiAvQml0c1BlckNvbXBv - bmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae3QAQ0AAADCoPdP - bQ43iEBhwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg - wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM - GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB - AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGPgeGDMvAAEKZW5k - c3RyZWFtCmVuZG9iagoxNiAwIG9iagozNjYKZW5kb2JqCjE5IDAgb2JqCjw8IC9MZW5n - dGggMjAgMCBSIC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggMjUy - IC9IZWlnaHQgMTA0IC9Db2xvclNwYWNlCjMxIDAgUiAvU01hc2sgNDQgMCBSIC9CaXRz - UGVyQ29tcG9uZW50IDggL0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7dAB - DQAAAMKg909tDjeIQGHAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED - BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA - gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY - MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED - BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY+B4Y - My8AAQplbmRzdHJlYW0KZW5kb2JqCjIwIDAgb2JqCjM2NgplbmRvYmoKMjkgMCBvYmoK - PDwgL0xlbmd0aCAzMCAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9X - aWR0aCAzMDggL0hlaWdodCA2MzAgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkgL0JpdHNQ - ZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHt2ulX - leUaBvAUZdrMbkCGTWwhBkEGBVFcECJhIGgZqEWyQNKUBFoYYgtDMhLRAmWJohE4oCSz - KKBm6/xr53424HABeXc6X3q7ng+nLr3Oxud3nuHdr+eddzgoQAEKUIACFPi/C6yy/Pi/ - kRmp1S+Hm0XHywmuNvP9O3gLWm5ua9asWfsvGDJNNzcX3//o5gITLmPl7uHhuTi8LDcW - Z+bp4eFuZjsP95fZ5sHM6nIXLS8vb5sMHxm+lhxmZmaG3l5enp4GThacrLe/xGZOMLPC - 3MVLuHx8/fz8/QMCAi08AgL8/f38fIXOW9wMm0tNe7SZRSZissK8bDbhEqugdXZ7cHBI - SEioJYdMLDjYbl8XFBgYIHA2m5dZbUZNudTmxdZ6eHrbfPz8DZdIhYWHh0dEREZGOiw4 - ZFoRETLBsNDQEAPn7+dj8/b0mF9rmlt0nsysMV+/gCB7cOj68AiH493oaKdzQ4xlxwan - Mzr6XYcjInx9aLA9KEAWm6y1+aX2tv1p9qVsSxHzMWIC5oiKdsbExsXFJyQmJm6cH0mW - GQsTkqklxMfFxcY4o6McwmbUfERNNujb9+cCmbfNJRYWGRUtXgkbk5NTUlPT0mVstuAw - 80pLTU1JTt6YIG7RUZFhLjXZoPNof7rSFsl8/ALtIWGR7zpj4xKFK31LxtasrG3bs1+N - HRYYr2aTvX1bVtbWjC3pApcYF+t8NzIsxB7o56NAc5F5eNp8/QPtoRFRztiEpJS0LZlZ - 2TtycvPydubvMqPAYsM1qfydeXm5OTuyszK3pKUkJcQ6oyJC7YH+vjZzqMn2XHGlCZmb - nGVCFhQc5oiOiU9KTc/ctiM3b9cHhR8WFe8pKSktLd1ruSGTKinZU1z0YeEHu/Jyd2zL - TE9Nio+JdoQFBxk097XmmWMltFULZAHrQsIdG+ISU9K3ZufsLNhdXLLvo/2flJcfOHjI - ouPggfLyT/Z/tK+keHfBzpzsrekpiXEbHOEh6wIW0FYyE7I17p7evv5CFhUTn5yWmZ2b - X1i89+Pyg59WVFZWVR05UmPGF5YarikdOVJVVVlZ8enB8o/3Fhfm52ZnpiXHx0QJmr+v - nGnydLsCmnnK8PDy8Q8yZAmbNmfl5Bfu2Vd2qKKyuubY8RO1J0/W1dXX1zdYbMiU6upO - nqw9cfxYTXVlxaGyfXsK83OyNm9KMGhB/j5eriNt2c1pdqac/36BwUKWmJKx/f2CIhE7 - XH30+Ff1Xzeeamo63XzGoqP5dFPTqcav6786frT6sKgVFby/PSMlUdCCA/3MPbDCQlsl - y8yQ2cMcMQkpGdl5hSX7RexYbX1jU/O3Ld+1nmtr+96io63tXOt3Ld82NzXW1x4Ttf0l - hXnZGSkJMY4weeSwecrdudzmdC0zL58Ae2ikM36TkO0uLfus6mhtw6nmlta28+0XOjou - dl6y6Oi82NFxof18W2tL86mG2qNVn5WV7ha0TfHOyFB7gNmdyy60hWUmh1l0XPLm7Xm7 - 95ZXHDle13impe2HC52Xfu7q7r5y9WqPJcfVq1e6u7t+vtR54Ye2ljONdcePVJTv3Z23 - fXNyXLQcaSsutNWr5QLwDbCHyWGWlvV+YWn55zUnGppazrV3XO660nOt9/qNPhk3LTjM - vG5c773Wc6Xrckf7uZamhhM1n5eXFr6flSZHWpg9wFcW2urVS24BszXlNAsyOzMlI6eg - pKyi5sTXzWfPd1zu7untu/lL/68DAwODg4O3LTdkUjK1X/t/udnX29N9ueP82eavT9RU - lJUU5GSkmN3pWmjLbE7Zmu7mNAuLik1Kz95ZtP+zaiFrbe/s6um92T9w+87de0ND92U8 - sNwwsxoaunf3zu2B/pu9PV2d7a2CVv3Z/qKd2elJsWah+Xi5L3MLrJKt6e0XGBLhjE/d - mlu471DVlw1Cdqn7Wl//4N2hB8O/PRxxjVHLjfl5Pfxt+MHQ3cH+vmvdlwSt4cuqQ/sK - c7emxjsjQgL9vGVzLrk5XVvT377eEbsxPTt/T9nho3VN3wlZ762BO/eHR0bHxscnJicn - pyw5ZGIT4+NjoyPD9+8M3OoVtO+a6o4eLtuTn52+Mdax3u4vjxtuSw4019aUx9nouE2Z - ObLMqmsbW853CtngveGRsYmpqUfTjy09ph9NTU2MjQzfGxS0zvMtjbXVstByMjfJ1Rkc - 6NqccAnIcWa2ZmjkhsS0bXnFZYePNTSf6+i6dmtwaHh0Ymr68ZOZ2fkxZ7mxMLGZJ4+n - pyZGh4cGb13r6jjX3HDscFlx3ra0xA2RoWZzLjnQzHFm81u3Pio2ecuOgr2yzE61tF/u - 6Ru499vY5PST2dm5p88sPp7Ozc4+mZ4c++3eQF/P5faWU7LQ9hbs2JIcG7V+nZ9t6YEm - Zp42f7tszZTMnN0fVxytb27r6L7ef2d4dHJ6ZlbAnv8u44VFh5nb82fPns7OTE+ODt/p - v97d0dZcf7Ti4905mSmyOV0HGl4Cq+TpzCcwOMKZkJqVV1RWebyx5YfLPTcHh0Ympmfm - BGwR6w8LjsW5CdvczPTEyNDgzZ7LP7Q0Hq8sK8rLSk1wRsiBJpcAXJyr3dy9fOU4i0lM - z95VcrD6q6bWC129/XeHx6Yezz57Lp8KVv+xwIApySSfP5t9PDU2fLe/t+tCa9NX1QdL - dmWnJ8bIgebr5Y4Xp5h5y5cAR2ySHGf7Pq2pa267eKVvYOjh+PTMUyCzgNZrU3gNzqA9 - nZkefzg00HflYltzXc2n++RAS4p1yFcB76Vm5tqUK+C95Iycwo8qjjV8e/5Sz83bD0Ym - ZZnJxnztk/947Qda4F9fn9mLF7/LQpsceXD7Zs+l8982HKv4qDAnI/k9cwmYi/PNhw15 - 1LD52cPk6Wxr7of7D3/Z2NL+07Vf7sjWfDInZosfbAGjZaewOD8xm3sim/POL9d+am9p - /PLw/g9zt8oTWphdLs6lZvPXZry5Aj6pPHHq7I8/m+Ns/NHMnGzNhc9c9udZ4hcXJiib - c27m0bg50H7+8eypE5WfmEsgfv7iXGImjxoB8qhhrs3isqrab1o7uq7/eu+hmMlxZnmy - //xnEU0OtEfjD+/9er2ro/Wb2ip5qpWLU8wC5NsT7k1jFhzulG8BO/eUV8m12dF9Q66A - ienZl2aWWFArTmIeTS6B2ekJuQRudHfIxVlVvmenfBNwhgevaBYh35y255ccqD55+txF - YyZPZ+YKcH3eij/NIr/hmqS5BMwTmphdPHf6ZPWBkvzt8u0pYgUzH3kRtMH1eHbgyMnm - tk7zqLFwbZqPs4jMn0zDzHLh4jQPG51tzSePHHA9oG2Q10HyULt0b4rZ4iOteTwTs8H7 - r8z+5GdZ5rdemd0fdJnV1Sw+1P6Zmbw821V6qKbuzPeXrv67za5e+v5MXc2hUvkisDEm - UmFWTzNjVk+ztx0ib+xNmr2Ny/X7/18z1Y+0QGnx3pQ74K3rzLxydN2bC3cAnmcW4FBN - 4S1mb7xAo9k8Kc1US+uN0l8yk1fb8prWEbNxs+v5zOxNeX12f9S8pZWvTm98sIWDfBEw - b2pH75sXaIvPGps3xjjkRS2+3Ja/DjCvth0xSZvN3zp90TBv9kDM5sTMwkowNTGbEzPX - S8fvzzR8Yf7maXOSy8wL/kKAZgt2NINFpIg0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA - oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB - hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 - UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB5a+Z - efoGhjpiNm7O3lV6qKb+zPeXem4O3h+dejz77MUff8AnWzb+IWazj6dG7w/e7Ln0/Zn6 - mkOlu7I3b4xxhAb6eq51W/XOa2PV6rWePoEhkTEb01+aXe0bvD8yKWa/v/j3mL34Xcwm - R+4P9l19aZa+MSYyJNDHc+1qmi2zW/6g2TIqf/5Lf8XsHe5NF+ZbzF47zeRf32L277gF - /pAr4E/PM5ot2aY0W0Ly1l/4e2Z18nz2+rPGv3Rv1rmez149ayy/NxPl+azkYE1dc1vn - ldeez/6FZlc625rrag6W7MpOT1x8PlvOLGKDy+zAkZOnjdnA0OIzrazat67sf3xBJrl4 - BwwN9InZ6ZNHDrjMNkTMP9MuMbMFBItZ2vb8kgPVJ0+fu9h9Q8wmpl3fA8zH/eNN3jIB - M0eX2fTEyNDAje6L506frD5Qkr89LXFDRHCATb4HLGcW7kxM27ZzT3nVV02tHcbsoZg9 - fS5fOM14y8/8h//2/BxfPH86Oz3x0Jh1tDZ9VVW+Z+e2tERn+Ipm9vDohNSsvOKyqtpv - Wju6rv967+H4o5mXZpZGmyf7Q8xmHo0/vPfr9a6O1m9qq8qK87JSE6LD7cutszWeNn8x - ixezok8qT5w6++PPvf13h8Vs7vmLhYVmYbRFshfP58Rs+G5/788/nj11ovKTIjGLFzN/ - m+ca3JtrPGx+9rDouE1bcz/cf/jLxpb2n679cmd4bOrJnHmxsTD+4ftvxT/+4vzka8Dc - k6mx4Tu/XPupvaXxy8P7P8zduikuOszuZ/NYxszbb936qPeSM3IKP6o41vDteXmBdvvB - wsX5Es18+Io/+R/5G4tc5p8vFr46Pbgtr8/Of9twrOKjwpyM5Pei1q/z815q5ubu7RcU - 6ohN2rKjYN+n5gHtonnYeDg+bQ60l7vTfPI/kmbFP7SZ0cKQacpxNj0uV0DflYvm8ezT - fQU7tiTFOkKD/Lzd3XBvurl7yYvayJj5h9pquTgvdJkDbcy8qQU08yNW/DP8g35j0eo1 - MvOWdswcZ10X5NqsXnyklde0XkvMVrmZF7XBEU5zcRaVVR5vbPnhsrzdNk9oM3PPnv8u - /xu4BvwcS8TFuf3+/NncjHk6kzfbl39oaTxeWWaugARnRLB5Tfvmq+133jEvt10XZ1xK - Zs7ujyuO1je3dXRf778zPDo5PTP79JmwyVj8dKv908zt+bNnT2dnpidHh+/0X+/uaGuu - P1rx8e6czJS4+WsTXm27zOTilEsgNlkOtL2HqmtPtbRf7ukbuPfb2OT0k9nZOWGz9ng6 - Nzv7ZHpy7Ld7A309l9tbTtVWH9orx1lyrLkCbB7LmK3x8PaTA02+PW2Tp9rDxxqaz3V0 - Xbs1ODQ8OjE1/fjJzOz8mLPcWJjYzJPH01MTo8NDg7eudXWca244dlieaOVbwIbI0EDX - tfnGX6HI96jVa9y95EALlye0zJzCfbLQGlvOd3b33hq8NzwyNjE19Wj6saXH9KOpqYmx - keF7g7d6uzvPtzTKMttXmJMpT2fhcpx5uePjmZjJJSAH2npHrPx1Xf6essNH65rOtl8S - tIE794dHRsfGxycmJyenLDlkYhPj42OjI8P37wwI2aX2s011Rw+X7cnPTt8Y61hvvgWs - xUeN+QNNNmdIhDM+dWuuLLSqLxuaWwXtWl//4N2hB8O/PRxxjVHLjfl5Pfxt+MHQ3cH+ - vmtC1trc8GWVLLPcranxTnkRJFtzyXFmzMzmDLCHRcUmpWfvLNr/WfWJrwWts6un92b/ - wO07d+8NDd2X8cByw8xqaOje3Tu3B/pv9vZ0dQrZ1yeqP9tftDM7PSk2Kswe4NqaeJyJ - mdmc8lUg0hmfkpFTUFJWUSNoZ893XO7u6e27+Uv/rwMDA4ODg7ctN2RSMrVf+3+52dfb - 03254/xZIaupKCspyMlIiXdGypcA19ZcYvbO6tVrPbx8zUKLSUzLer+wtPzzmhMNTS3n - 2jsud13pudZ7/UafjJsWHGZeN673Xuu50nW5o/1cS1PDiZrPy0sL389KS4wxy8zXS7Ym - fHMy7x9lc7oWWohcncmbt+ft3lteceR4XeOZlrYfLnRe+rmru/vK1as9lhxXr17p7u76 - +VLnhR/aWs401h0/UlG+d3fe9s3JcmmGuJbZmjf/zxrzb2zN5vQwJ5rZnZsysvN2l5Z9 - VnW0tuFUc0tr2/n2Cx0dFzsvWXR0XuzouNB+vq21pflUQ+3Rqs/KSnfnZWdsMjvTnGYe - cmsu3ZovF1qgPcwRk5AiaIUl+w8drj5WW9/Y1Pxty3et59ravrfoaGs71/pdy7fNTY31 - tceqDx/aX1IoZCkJMY4we6A5zZZdZsZMFppcA/JgK0daSsb29wuK9pWJ2tHjX9V/3Xiq - qel08xmLjubTTU2nGr+u/+r4UREr21dU8P72jBQ5zORxVshWWmbyWCsnmuxO/6AQQUvY - tDkrJ79wj6hVVFbXHDt+ovbkybq6+vr6BosNmVJd3cmTtSeOH6uprqwQsT2F+TlZmzcl - CFlIkL/ZmWuWuwHmbwG3Ne6e3r7+6wxafHJaZnZufmHx3o/LD35aUVlZVXXkSI0ZX1hq - uKZ05EhVVWVlxacHyz/eW1yYn5udmZYcb8jW+ft6e7qvWf40W0Bb6+5p8w0QNMeGuMSU - 9K3ZOTsLdheX7Pto/yfl5QcOHrLoOHigvPyT/R/tKyneXbAzJ3trekpi3AaHkAX42jzd - V7gAXHfnqtVypBk0/6DgMEd0THxSanrmth25ebs+KPywqHhPSUlpaeleyw2ZVEnJnuKi - Dws/2JWXu2NbZnpqUnxMtCMsOMh/gWzZS3PxecMcaQYt0B4aEeWMTUhKSduSmZW9Iyc3 - L29n/i4zCiw2XJPK35mXl5uzIzsrc0taSlJCrDMqItQeaMhch9lyzxnzZObuFDQ503z8 - Au0hYZHvOmPjEpNTUtO3ZGzNytq2PfvV2GGB8Wo22du3ZWVtzdiSnpqSnBgX63w3MixE - HjJ85Cwz5/+fkb1Cs/kFBNlDwyKjomNi4xI2Jgtcalq6jM0WHGZeaanClbwxIS42Jjoq - MizUHhTgZ1ORvbNqYaV52XxcauvDHVHRTnGLi09ITEzcOD+SLDMWJiRTS4iPEy9ndJQj - fL1LzMfmtbDK/nyZyR41F4E51LxsvkYtOHR9eITD8W50tNO5IcayY4PTGR39rsMRIWDB - Zo35ipgcZW5v25gvLwJBEzVvWWv+gUHr7CGhoWHh4eEREZGRkQ4LDplWRIRMMCw0NMS+ - LijQ389HtqXHWjWZrLT5peZu1posNr+AQANnDw4OCRE9Kw6ZWHCw3XAFBvjJEjNrTA5/ - s8jeui9fuz7NBpUb1NPL22bzETh//wCxs+4ICPD3Fy4fm83by1POMZfYWy7MRa6F/SlL - TdQMm4e4GTihk+FryWFmZmbo7SVessLWrjFr7C8ssgU9s0NXu5nVZuBEbmF4WW4szszT - w3CZFfY/gb222lxwZsVZf6yR5WW4/ocV9sY2XSXD9TGu/3Cz6Hg1QzPfNwD+TjAfZu3x - d3T436UABShAAQpQYAWB/wIyjvCaCmVuZHN0cmVhbQplbmRvYmoKMzAgMCBvYmoKNzcy - OAplbmRvYmoKMzIgMCBvYmoKPDwgL0xlbmd0aCAzMyAwIFIgL1R5cGUgL1hPYmplY3Qg - L1N1YnR5cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UK - L0RldmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29k - ZSA+PgpzdHJlYW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aup - iXZwlDqYMuaIy+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+ - j4+PV94R8I6AdwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFd - Pz9sGP5PfgwcsBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOURO - g0ikwEA0AJAAEP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO - 5BBxEpkM2MAcEspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkI - G4jZERERHA6Xy+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8 - S3y+QBAlxL2iBAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJ - VCqNcSkWd3IbA4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6 - jGMhfwnx8XKZLEYC/PxILhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6Xj - SAeuVGmpSmVKUqICBkAaLRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2do - NJlZ2Ug5OBVmLitTo8lQp6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF - 4th4RXJqeoYm+1ft1bz8Ap2usLCwCLcCczpdQX7eVe2v2ZqM9NRkRXysWMjnsVkhCN7/ - AprrToI/50anh4ZF8KKipXJFikqdmZObryu+VnKjtLSsvALnKi8rLb1Rcq1Yl5+bk6lW - pSjk0ugoXkRYKN0NfxI7oJ/3DwwKpgF6pFAsS0hWZWRp84uul5bfrKyurqmpqzMg/Q+X - wqzV1dXUVFdX3iwvvV6Ur83KUCUnyMTCSICnBUPNwyrnBHg0uwWQKLQQhC6Ju6xUZ2kL - ivUVldW1hobGpuaWFqOxtbW1DacCa0ZjS0tzU2ODoba6skJfXKDNUisvx0kQfAiNQsJK - /tikRxkPfY7KYAG6VJ6UdiUnD8irausb77TeNbV3dHSa7+Fc5s6OjnbT3dY7jfW1VUCf - l3MlLUkuBXgWg4r63QmBPwdhR+hMNk8okSepNFpdCZA3NLeaOsz3LQ+6e6zWP3Auq7Wn - +4HlvrnD1NrcAPQlOq1GlSSXCHlsmOrIgdDrj0t6LOwkCp0ZzhWI4wA9t1B/q6a+ua3d - bOm29vb122wDg0M41+CAzdbf12vttpjb25rra27pC3MBPk4s4IYz6Sjrjw28O+xQ7Pxo - 2eU0TW5RaWVdo9F0z2J92D849GhkdHRsfNyOa42Pj42OjjwaGux/aLXcMxkb6ypLi3I1 - aZdl0Xwo+RMD7+sLjS6YzmRDsScor2gLS38zNLV1WHr6bMMjY/aJyanH06AZHAv5ezw1 - OWEfGxm29fVYOtqaDL+VFmqvKBOg5NlMejAE3tf3SLdDKQ/VHoIyXp6kztHpKw1Nd81d - vbbhUfvk9MzT2Wdzc3MOh+M5bgXmwOKz2acz05P20WFbb5f5bpOhUq/LUSfJUdZjgT8m - 6SHl/VG1syNFsQpVZl7JrVpA7+4bHLFPzszOPZ9fWFxaegF6iVshd0tLiwvzz+dmZybt - I4N93QBfe6skL1OliBWhwFNI/sd0u3OQ8kFURhhHII5PydAWV9TcbgP0odGJ6VnHwtLL - 5Vcrq5jWcCuXv5VXyy+XFhyz0xOjQwDfdrumolibkRIvFnDCGNQgSPojnR5LeRrzIk8U - o1BlFeir6o0dDwB98snc/Ivl1bX1jY3Nra2tbVwLDG5ubKyvrS6/mJ97MgnwDzqM9VX6 - giyVIkbEu8ikwTTnd6TgsZSHZQ0/Oi5ZDWGvbTZZegcB3bG4vLq+ub392vnmTMj5ent7 - c311edEB8IO9FlNzLQRenRwHrZ7FwJL+ULODckcpH86NkiakavL1VQ1t5h7byMQTx9Ly - 2ua2883O7p5L+7iV2+Duzhvn9uba8pLjycSIrcfc1lClz9ekJkijuOEo6Y8UPCp3MjX0 - YqRIlpieUwRhb7f0Ddun5xZfrW85d/b29t++OyN6u7+3t+PcWn+1ODdtH+6ztEPgi3LS - E2WiyIuhVPLRggf2QDKNCSkvT1bnXq+sbzVbbaNTs/PLa1vO3T0Af/836APOhTy+f/fu - 7d6uc2tteX52atRmNbfWV17PVSfLIemxgj/c7M7B7E5hsDgCSbxSk6evbjRZHg7bZxxL - q5vO3X0A90D/g2N5PAL+/q5zc3XJMWMffmgxNVbr8zTKeImAAwUPze5Qo/f18ycFQ7kL - pQpVtq689k5Hd//I5OzC8vr2m7137+Gqh5g/4kiHrIHZ9+/23myvLy/MTo70d3fcqS3X - ZasUUiEUfDDJ/3CjB/YgWNTxRLFQ7sU3DUazdWBsem5pZcO5+/YQOo6oP7Py2QAg+Le7 - zo2VpbnpsQGr2Wi4WQwFHyviwdIu6Cg7avPQ6n6RJam11yob2u73Dtlnnr9c3YKwQ8J/ - duV/PvtCHP3zc4cfPvwNgd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLun - ZFwtqbptsvT9NfF0HlJ+Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ - 6I+yu9q8GLW6G9VN7V1/PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+g - Zid2Nfoj7DDF0WGKQ20+X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+u - gdUNNHpgp8Oq9nDOI3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8 - aoNGX1NakAkrO0EE60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCn - s6W2TJeVBqtazgnsFLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbB - R8FtLCxujuY8sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j8 - 52AfH/rjntFQUQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf - +Srcffwj2c/S9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n8 - 6r0M3L8T9h6W2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI - /I6Zz3HvFnad/XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A - 6HaE3ROKAk/YvcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4 - ndAVeSKe7YNFHg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxG - tIfKhY8qn2BndSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2C - dwS8I+AdAe8I/BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKMzMgMCBvYmoKMjc2MApl - bmRvYmoKNDIgMCBvYmoKPDwgL0xlbmd0aCA0MyAwIFIgL1R5cGUgL1hPYmplY3QgL1N1 - YnR5cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0Rl - dmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+ - PgpzdHJlYW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZw - lDqYMuaIy+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+P - V94R8I6AdwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9s - GP5PfgwcsBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ik - wEA0AJAAEP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBx - EpkM2MAcEspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZ - ERERHA6Xy+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+ - QBAlxL2iBAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqN - cSkWd3IbA4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMh - 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 - NHpgp8Oq9nDOI3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNG - X1NakAkrO0EE60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2 - TJeVBqtazgnsFLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8Ft - LCxujuY8sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852Af - H/rjntFQUQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Src - ffwj2c/S9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M - 3L8T9h6W2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Z - z3HvFnad/XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE - 3ROKAk/YvcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAV - eSKe7YNFHg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfK - hY8qn2BndSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8 - I+AdAe8I/BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKNDMgMCBvYmoKMjc2MAplbmRv - YmoKNDQgMCBvYmoKPDwgL0xlbmd0aCA0NSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5 - cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0Rldmlj - ZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+Pgpz - dHJlYW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqY - MuaIy+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R - 8I6AdwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5P - fgwcsBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0 - AJAAEP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM - 2MAcEspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERER - HA6Xy+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAl - xL2iBAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkW - d3IbA4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMhfwnx - 8XKZLEYC/PxILhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6XjSAeuVGmp - SmVKUqICBkAaLRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2doNJlZ2Ug5 - OBVmLitTo8lQp6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF4th4RXJq - eoYm+1ft1bz8Ap2usLCwCLcCczpdQX7eVe2v2ZqM9NRkRXysWMjnsVkhCN7/AprrToI/ - 50anh4ZF8KKipXJFikqdmZObryu+VnKjtLSsvALnKi8rLb1Rcq1Yl5+bk6lWpSjk0ugo - XkRYKN0NfxI7oJ/3DwwKpgF6pFAsS0hWZWRp84uul5bfrKyurqmpqzMg/Q+XwqzV1dXU - VFdX3iwvvV6Ur83KUCUnyMTCSICnBUPNwyrnBHg0uwWQKLQQhC6Ju6xUZ2kLivUVldW1 - hobGpuaWFqOxtbW1DacCa0ZjS0tzU2ODoba6skJfXKDNUisvx0kQfAiNQsJK/tikRxkP - fY7KYAG6VJ6UdiUnD8irausb77TeNbV3dHSa7+Fc5s6OjnbT3dY7jfW1VUCfl3MlLUku - BXgWg4r63QmBPwdhR+hMNk8okSepNFpdCZA3NLeaOsz3LQ+6e6zWP3Auq7Wn+4HlvrnD - 1NrcAPQlOq1GlSSXCHlsmOrIgdDrj0t6LOwkCp0ZzhWI4wA9t1B/q6a+ua3dbOm29vb1 - 22wDg0M41+CAzdbf12vttpjb25rra27pC3MBPk4s4IYz6Sjrjw28O+xQ7Pxo2eU0TW5R - aWVdo9F0z2J92D849GhkdHRsfNyOa42Pj42OjjwaGux/aLXcMxkb6ypLi3I1aZdl0Xwo - +RMD7+sLjS6YzmRDsScor2gLS38zNLV1WHr6bMMjY/aJyanH06AZHAv5ezw1OWEfGxm2 - 9fVYOtqaDL+VFmqvKBOg5NlMejAE3tf3SLdDKQ/VHoIyXp6kztHpKw1Nd81dvbbhUfvk - 9MzT2Wdzc3MOh+M5bgXmwOKz2acz05P20WFbb5f5bpOhUq/LUSfJUdZjgT8m6SHl/VG1 - syNFsQpVZl7JrVpA7+4bHLFPzszOPZ9fWFxaegF6iVshd0tLiwvzz+dmZybtI4N93QBf - e6skL1OliBWhwFNI/sd0u3OQ8kFURhhHII5PydAWV9TcbgP0odGJ6VnHwtLL5Vcrq5jW - cCuXv5VXyy+XFhyz0xOjQwDfdrumolibkRIvFnDCGNQgSPojnR5LeRrzIk8Uo1BlFeir - 6o0dDwB98snc/Ivl1bX1jY3Nra2tbVwLDG5ubKyvrS6/mJ97MgnwDzqM9VX6giyVIkbE - u8ikwTTnd6TgsZSHZQ0/Oi5ZDWGvbTZZegcB3bG4vLq+ub392vnmTMj5ent7c311edEB - 8IO9FlNzLQRenRwHrZ7FwJL+ULODckcpH86NkiakavL1VQ1t5h7byMQTx9Ly2ua2883O - 7p5L+7iV2+Duzhvn9uba8pLjycSIrcfc1lClz9ekJkijuOEo6Y8UPCp3MjX0YqRIlpie - UwRhb7f0Ddun5xZfrW85d/b29t++OyN6u7+3t+PcWn+1ODdtH+6ztEPgi3LSE2WiyIuh - VPLRggf2QDKNCSkvT1bnXq+sbzVbbaNTs/PLa1vO3T0Af/836APOhTy+f/fu7d6uc2tt - eX52atRmNbfWV17PVSfLIemxgj/c7M7B7E5hsDgCSbxSk6evbjRZHg7bZxxLq5vO3X0A - 90D/g2N5PAL+/q5zc3XJMWMffmgxNVbr8zTKeImAAwUPze5Qo/f18ycFQ7kLpQpVtq68 - 9k5Hd//I5OzC8vr2m7137+Gqh5g/4kiHrIHZ9+/23myvLy/MTo70d3fcqS3XZasUUiEU - fDDJ/3CjB/YgWNTxRLFQ7sU3DUazdWBsem5pZcO5+/YQOo6oP7Py2QAg+Le7zo2Vpbnp - sQGr2Wi4WQwFHyviwdIu6Cg7avPQ6n6RJam11yob2u73Dtlnnr9c3YKwQ8J/duV/PvtC - HP3zc4cfPvwNgd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLunZFwtqbpt - svT9NfF0HlJ+Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ6I+yu9q8 - GLW6G9VN7V1/PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+gZid2Nfoj - 7DDF0WGKQ20+X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpg - p8Oq9nDOI3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1Na - kAkrO0EE60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeV - BqtazgnsFLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxu - juY8sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rj - ntFQUQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj - 2c/S9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T - 9h6W2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3Hv - Fnad/XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROK - Ak/YvcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe - 7YNFHg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8q - n2BndSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+Ad - Ae8I/BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKNDUgMCBvYmoKMjc2MAplbmRvYmoK - NDAgMCBvYmoKPDwgL0xlbmd0aCA0MSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUg - L0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdy - YXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJl - YW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaI - y+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6A - dwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5Pfgwc - sBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAA - EP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAc - EspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERERHA6X - y+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAlxL2i - BAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkWd3Ib - A4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMhfwnx8XKZ - LEYC/PxILhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6XjSAeuVGmpSmVK - UqICBkAaLRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2doNJlZ2Ug5OBVm - LitTo8lQp6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF4th4RXJqeoYm - +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 - sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQ - UQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S - 9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W - 2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad - /XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/Y - vcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNF - Hg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2Bn - dSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I - /BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKNDEgMCBvYmoKMjc2MAplbmRvYmoKMzQg - MCBvYmoKPDwgL0xlbmd0aCAzNSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0lt - YWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkg - L0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0K - eAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaIy+TC - UdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6AdwS8 - I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5PfgwcsBGz - f0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAAEP9v - wkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAcEspk - 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 - PvwNgd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLunZFwtqbptsvT9NfF0 - HlJ+Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ6I+yu9q8GLW6G9VN - 7V1/PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+gZid2Nfoj7DDF0WGK - Q20+X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpgp8Oq9nDO - I3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1NakAkrO0EE - 60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeVBqtazgns - FLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxujuY8sHuW - Nmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQUQgL - uxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S9I6t - a93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W2M8u - iPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad/XcL - u07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/YvcBY - 1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNFHg7y - IuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2BndSJ4 - Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I/BQj - 8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKMzUgMCBvYmoKMjc2MAplbmRvYmoKMzggMCBv - YmoKPDwgL0xlbmd0aCAzOSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdl - 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 - 6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad/XcLu07z - biGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/YvcBY1qPt - 7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNFHg7yIuKZ - TrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2BndSJ4Nz7E - n3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I/BQj8C9p - pK71CmVuZHN0cmVhbQplbmRvYmoKMzkgMCBvYmoKMjc2MAplbmRvYmoKMzYgMCBvYmoK - PDwgL0xlbmd0aCAzNyAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9X - aWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkgL0JpdHNQ - ZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHtnPlX - Uukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaIy+TCUdMyyaXM - 3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6AdwS8I+AdARiB - c2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5PfgwcsBGzf0BAoEck - 3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAAEP9vwkcVjiLu - D9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAcEspkslhhYWHh - uBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERERHA6Xy+XhWGCPwwGj - 7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAlxL2iBAI+/xKPx4m4 - GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkWd3IbA4sScXS0SCjg - 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 - /Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpgp8Oq9nDOI3ZWhABW - dZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1NakAkrO0EE60R2Dqxo - 07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeVBqtazgnsFLiBjcKm - 97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxujuY8sHuWNmh6B3bH - iwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQUQgLuxgh9xTs - rT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S9I6ta93z+4+I - u5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W2M8uiPrM6jyB - n1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad/XcLu07zbiGR - 3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/YvcBY1qPt7wTc - Aw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNFHg7yIuKZTrCb - AnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2BndSJ4Nz7En3Bn - tLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I/BQj8C9ppK71 - CmVuZHN0cmVhbQplbmRvYmoKMzcgMCBvYmoKMjc2MAplbmRvYmoKNDYgMCBvYmoKPDwg - L0xlbmd0aCA0NyAwIFIgL04gMSAvQWx0ZXJuYXRlIC9EZXZpY2VHcmF5IC9GaWx0ZXIg - L0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4AYVST0gUURz+zTYShIhBhXiIdwoJlSmsrKDa - dnVZlW1bldKiGGffuqOzM9Ob2TXFkwRdojx1D6JjdOzQoZuXosCsS9cgqSAIPHXo+83s - 6iiEb3k73/v9/X7fe0RtnabvOylBVHNDlSulp25OTYuDHylFHdROWKYV+OlicYyx67mS - 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 - gQc1LhFnhxB0iPJwboTKvcL1/8i0x/raOvyt2x8WYW0HY0FYZiwg2JQoT/S14+ml9/fa - EOT4QHMczMN+EWx+BGPi+uG6ESEFDIAbXI35AC8gCXBAF+j9fcXAPAYeB8OzXiAclps+ - kPsjZX8w9vtfWpLA+8Be5IFOAJyVw0DQSb/kMNjWv1v3gC1HgEBYLgKEydTJzMrs/CND - 9Bp44PmPlul/MIfWDld4KOsHPGGpPzzR/gFP9B7U5B1ZFByjYu+LFEbKIRWROkh1pAYS - CzBINJIDSCIVkMpIbaQmUhWew76cb5v/Zy2H++P+z32a/lkzvHL8P+x/eAV+8HeMg/od - 3mlABp+P0tNE9Eholtj9WyN4RROIhG5wSEyYn48vAaMNf73wksAY4z2kJDByMjJY8D+q - bG8vCmVuZHN0cmVhbQplbmRvYmoKNDkgMCBvYmoKMzkxMAplbmRvYmoKMzEgMCBvYmoK - WyAvSUNDQmFzZWQgNDggMCBSIF0KZW5kb2JqCjUwIDAgb2JqCjw8IC9MZW5ndGggNTEg - MCBSIC9OIDMgL0FsdGVybmF0ZSAvRGV2aWNlUkdCIC9GaWx0ZXIgL0ZsYXRlRGVjb2Rl - ID4+CnN0cmVhbQp4Aa1YZ1QUy7auHgaGnBkyDFFyRhhyjkNOSlByZkhDDgqCICBBlCQi - CCiCIiDpYCCoiCiCgogKqIgKEiQISH49cDx33XfXXe/Pq7Wm66uvdqiuXd17dgPAgHEL - CQlEAACC8IQwa0MdzLHjjhjUO4AEVIAVqAION4/wEG1LSxws8l/a+iiAiFPDkkRb50Jk - 7PQDR6ZD8cE5Ketrhv9F6Q9NGwY7BACSgAlmn0OsRcTuh9iWiKMIIQRYxpeIPXzdPGEc - D2OJMFtrXRjXwJjW5xC3E7H7Ie4j4kgPH6LuGABkjHhPPzwAqHkYa3h6hXvA00S/np7h - HkEwzgUAoRMUFAzbpx+BeRGPkDBYl34HxoLEfYF7uLnOAKDMDNuw/hcXchSAJngb+Tj/ - xQm1AYBGAlDX/i9u1fpgryD0YLi3vNyBOYhaBwDSyf39VWF4bRcA2M3b39++tr+/WwkA - yTgAXYEeEWGRB7LwjUADAPxf48N7/luDBA4OMcB8IAzMQ8kIVRIhpDVpHUqJfIPyNw0T - nQKDN1MGSzFrJrsrJy9XDQ8drwemhZ9KwFfwmfCRI5kiS2JO4p2SolLnpVdlbeXqFagV - Tx69owywhippqp1qmxrSmgFaVdqTuqx6OP00g07DdWMJk5OmebgesxULjKW5FcG6zGbI - jtc+0uHpcXbHAKdW570TRiezXAfdGT1sPQu8Pvhw+7r51fqvBqoFpeNfBC+Hkoahw4UI - ShHGkU5RgdHxMTmxV+Ma43sS3iTOnNpKoksWOqOSYp7qctY+DZvOlr5xbizjXmZpVuJ5 - 12ydHP6c/dz3eS0X8vI9Lypforz0rqCmkFBkWaxbonZZsVT8CncZVdna1fHyhxVXrkVV - mlfxV61Wd17PvGFXw1UzdbO2NrYu4JbX7ZP1x+6YNWg1Sjdx3SW7u9A83NLaWtQW2W77 - l1wHbcfcvWf3qx+cfujUKd9F0fW5u7nn3COnx5JPwJPh3sqnhD79Z+hn3/pbnqe9cBgQ - Gdh5OTiYM2Q0tPOq8XXgsOjw95GaNwGjMqMbbx+OnX1n8R79fuJD1bj/hNTE8mTjx+hP - +p9ZP/+Yav2SPI37yvD11bec70bfd2fqZm1nt3+UzCnNvZ73nt9ayFgUXBz8eXZJa2lz - uXklZFVqdeFXw1rUuu4G08bM797N2q0L28k7MbsRexH7lvv7cPyVwSMIjzhKwodUIk0h - mycPp+ShektTSxfDgGNiZx5Fn2ETYq/nFOIK4W7gWcYo8CXyvxBkE/IT7hBhFPUUa5Wg - lHSWqpFeklWXi5e/r7B9VEbJSTkCm61SDZ+Ct+rzmpAWs7a4jraurZ6vfqxBlmGZUaPx - E5NR0++4LXMmCyPLs1YPrH/ZSti52mc7dB5bcGR30ncOdbl8ou/kqhvG3dojybPRa9qH - 3lfAT9hfLEAiUDpIEa8SrBliEGoe5hDuTgiIiIk8F1UYfTPmYezruG/xqwkriZ9PPTvd - lFSanHkmIsU91fwsNo0/HZX+49yLjPrM9Cz388rZVNkfcmpzE/PCL3jm213UvyRbwFEI - CqeKeorLSqIum5Xyla5c6SrLvnq8nL98rqL1WmpldBW+2vu68w3LGu2b0rWcdci6+VvD - t9vqL9+Ja3BpVG/ibtq7+7G5u6W8NaXNu93gL+EO0o7pe133Sx/EPLTvlOui7ZrrftZz - /VHKY48nur2CT1FP5/qePavuP/3c6QV2gG1g4+W7wfahy68SXrsO64wIvEG+mR598rZy - LOndiffYD+zjyPGliU+TTz82fCr4HDPl+EV1mmN6HT4Htd/PzDjNyv+g/vF17sF84UL4 - ot1PrSXZZakVuVXlXwZrDuveG+G/YzdjtoK2bXbEd9Z2q/cM9t7t6+1XHMRfEMRDCOgS - woQEg+QklSA7hiog/0yJpcqnXqTVpcuhf8VIzSTHrM+ihZZhxbAxslNwIDm2OTe51rjX - eFZ5lzHLfIv8MwIfBd8I9Qm3H7khkicaJeYgrizBKLEo2StVKh0ioy3LIDshd10+WEFR - YV2x/WiMElZpQ7kZG6oiowpUX6tVq0drmGnya25oDWhX6cTr2unJ6lPrzxn0G9YZZRuH - mtiaYnHcuB2zMfO7FjmW/lZG1oI2kM2k7X27Uvs4B6djWseFHCkdV5wmnPtcmk6UnEx0 - dXCTdqd0n/Ho86z1yvYm+Dj76vmJ+dP7rweMB3YFXcOnBLuGqIWyhu6ELYR/IYxG9Ebe - jSqJjotxjJWNI417E1+R4J8okTh/qu60XxJ/0ofkS2csUqhTnqdmnsWlUacNpOecs8pg - zniXWZ7lf14xG8oezLmaG5qnf4HjwlJ+98WUS0cvzRaUFdoUURX1FqeUGF6muTxaWnEl - rMzgKufV1fKXFTXwefKp0q/mrJ6/3nEjs8bzpmYtd+1e3dSt57db6svvZDVENbo1mdyV - a2Zv3m2ZbL3XVt5+56/OjpF7U/dXHoJOyi7Gbs4ezCOBxwJP+Hp5nrL3MT2j6Sft336+ - 8mLppfJg/tDca+XhlJHRUem358d+vSeMk0/c+3jxc/6Xzm+as6zz3kuGa/LbKcT4H+Y+ - Yk4gg3NVkRcAx1MBsGEDIPM9AEdKAGBxBcCSBgBbLED4rgGEeCqAnEXAn/zBBuSACTgJ - CCAdlIJ60ANGwDewCVFBPJAcZAA5QsFQKlQKNUMD0AwCieBH6CA8EOcQjYiPJHQk2iQE - khqScSQD0hB5CtmGXCIVI/UkrSCdJOMicya7QvYRJYDyRzWiNsn1yfPJP1PIUqRSfKBU - pMyjXKAyo6qjpqbGU7+mUaK5SktGG0z7ns6QroVemL6IgYYhmWGLkcD4kymYaZE5hHmW - xYnlJVoffZ9VkbWeTZytll2c/RaHLEcbpwbnUy4rrgluX/g8p/Ay8VZgZDDdfNZ8X/gj - BNACvYIJQopCS8K1R7xFBEWmRa+L+YpLiq9I3JM8I4WTZpWelmmQTZAzk+eV31D4prh0 - dEeZEsuiIqyqpGai7qoRr1mm9UR7TpdPz16/wOC9kZCxnYmHaSwu16ze/LXFvpWMdaBN - g+2uvZXDHTgHpjntuMSf2HINcCtzf+NJ42Xifd5nFH7rxQe8DcLiy0OoQk+HrRFCIhai - /KPnY8PithNyTvGd7kx2TAGp19PM03cybmedzGbJeZWXlm9wcb+go6iqpKm0q+xB+b1r - DVWV13NrEmsDbrnU2zTgmnDNtq2+7d4d1vdVH2K7lHqMHgf0lvR9fW42MDgUPaw0yvkO - /aF0YvWTxVTN9O53y9mCuZcLm0usKzy/2NcpN35sdm7n7h4/eH/Qwv8gFIExcAbB4Awo - BHWgEz4Bs2APYobEIV3ICYqAcqA6qA/6jkAhRBFmCALiCuIFYo9EnsSX5CrJKJIWjn0y - 8gFyi1SJNIK0hXSDDEuWQNaDokTZoK6ifpCrkGeRT1LIU2RRzFDiKJuoOKlSqZaoT1AP - 0mjTtNKK016j46IrpGehv8SAZihm5GasZJJgamPWZu5nMWDpQeugH7Masj5ns2abYPdl - X+NI5URz3uRS5xrh9udB8JTyHuUdxATwkfNV8+vA77EKQXchAaEZ4VtHQkWURSHRfrGL - 4iclxCR+Sz6WypV2lZGS2Zbtl7ssj1fAKaofVVfSUNbGaqkYqJqq2aif0AjWTNOq1O7W - mddj17cyyDEcNUabiJoa4bzNMsybLb5Z8Vi72FTZrtobOVQfp3GMdpp18Twx4Wrpdta9 - 22PHS9U7yee5H5d/eMDLICn8xeDt0MCwcYJVxNMojejWWIW4WwkSifWnFZMenDFP+XQ2 - PJ3iXGWmWtbb7PBcxrzb+eYXvxckF4kWv72ccUWtbLa85JpR5U517Q3nm3S1vbeS6jXv - 7DU+vpvV4twm1T7VUXTf8CFlZ1933iPPJ9inTH0b/Z9eDL3sHmp/fWukarRirPh91njA - pPrH3c+3vzh/JflWMaMzOzNXsGD5k3OZZJV+zWpjcZv6IP5oIAM//x4gAY59IxgAsxAZ - JAjpQV5QOnQbegPtIyQQLoh8xCsSFhJnkmqSn0gV5DnkGPycJ5AOk4mTpZJNoXRRN8hp - yWPIv1McpxiiNKd8SWVHNUEdSL1PU0SrQDtGd5pemn6a4QqjMxMv0wzzXRY8Whz9g7WO - Dc+uwL7N8Zgzm+sYtxD3Mk8n73mMM580P8T/VqBFsEgoUdj7iLmIiqiIGKs4SnxTYkFy - UuqVdK9Mu2ydXLl8sUKx4s2jD5QGlSexiyq7atTq7Bpimhpa9tpBOhm6dXpD+nuGUkae - xikmJabNuGGzTQsRS3era9bLtsZ2tx3YjxU6cjvVuOieGHeNcaf1uO6l5j3qG+pPG3Az - SAc/FhIQuh+eG8ETeStaKaY37lSCzynDJNEziJSRs6XpLhlsmc/OR+UI5D69EHKR6VJj - oWMxV8lMaWOZbzlPxUBlXDXv9Z4ar1pU3Z3bx++gGjqawpsVWhFt3X8pdjTdF3pQ0ynU - VdMj+6j7iUXvVF9CP9fzngG/Qdah/tfxI/Jvlt/efhf8vm+casJ48vzHic8yU0lfBr6i - vzl/L5v58INiTnLeaMF68dhPsyW1Zd7lnZUXq8W/LNdQa/Xr5uuLG/G/Ub/zN5k2z22B - rait8W3sduH2rx3rnbKdr7uSu4Td+3vIvWN7Pfvi+5eI8T+sl4j5A1DqBgcGh2FwunoH - w/+/S1BgBFyTHTRG+EqNdze3gHsingkhWNrCPRr+bYVH2ujDPT1cDtF7+xkY/40xnm56 - pjDmgnmZWF9dcxhTwxjnHWZgDWNYFzrm72ZiCWNaGOO98HY2MIbtQ/EhgQc1LhFnhxB0 - iPJwboTKvcL1/8i0x/raOvyt2x8WYW0HY0FYZiwg2JQoT/S14+ml9/faEOT4QHMczMN+ - EWx+BGPi+uG6ESEFDIAbXI35AC8gCXBAF+j9fcXAPAYeB8OzXiAclps+kPsjZX8w9vtf - WpLA+8Be5IFOAJyVw0DQSb/kMNjWv1v3gC1HgEBYLgKEydTJzMrs/CND9Bp44PmPlul/ - MIfWDld4KOsHPGGpPzzR/gFP9B7U5B1ZFByjYu+LFEbKIRWROkh1pAYSCzBINJIDSCIV - kMpIbaQmUhWew76cb5v/Zy2H++P+z32a/lkzvHL8P+x/eAV+8HeMg/od3mlABp+P0tNE - 9Eholtj9WyN4RROIhG5wSEyYn48vAaMNf73wksAY4z2kJDByMjJY8D+qbG8vCmVuZHN0 - cmVhbQplbmRvYmoKNTEgMCBvYmoKMzkxMAplbmRvYmoKMjggMCBvYmoKWyAvSUNDQmFz - ZWQgNTAgMCBSIF0KZW5kb2JqCjUyIDAgb2JqCjw8IC9MZW5ndGggNTMgMCBSIC9OIDMg - L0FsdGVybmF0ZSAvRGV2aWNlUkdCIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVh - bQp4AYWUTUgUYRjH/7ONBLEG0ZcIxdDBJFQmC1IC0/UrU7Zl1UwJYp19d50cZ6eZ3S1F - IoTomHWMLlZEh4hO4aFDpzpEBJl1iaCjRRAFXiK2/zuTu2NUvjAzv3me//t8vcMAVY9S - jmNFNGDKzrvJ3ph2enRM2/waVahGFFwpw3M6EokBn6mVz/Vr9S0UaVlqlLHW+zZ8q3aZ - EFA0KndkAz4seTzg45Iv5J08NWckGxOpNNkhN7hDyU7yLfLWbIjHQ5wWngFUtVOTMxyX - cSI7yC1FIytjPiDrdtq0ye+lPe0ZU9Sw38g3OQvauPL9QNseYNOLim3MAx7cA3bXVWz1 - NcDOEWDxUMX2PenPR9n1ysscavbDKdEYa/pQKn2vAzbfAH5eL5V+3C6Vft5hDtbx1DIK - btHXsjDlJRDUG+xm/OQa/YuDnnxVC7DAOY5sAfqvADc/AvsfAtsfA4lqYKgVkctsN7jy - 4iLnAnTmnGnXzE7ktWZdP6J18GiF1mcbTQ1ayrI03+VprvCEWxTpJkxZBc7ZX9t4jwp7 - eJBP9he5JLzu36zMpVNdnCWa2NantOjqJjeQ72fMnj5yPa/3GbdnOGDlgJnvGwo4csq2 - 4jwXqYnU2OPxk2TGV1QnH5PzkDznFQdlTN9+LnUiQa6lPTmZ65eaXdzbPjMxxDOSrFgz - E53x3/zGLSRl3n3U3HUs/5tnbZFnGIUFARM27zY0JNGLGBrhwEUOGXpMKkxapV/QasLD - 5F+VFhLlXRYVvVjhnhV/z3kUuFvGP4VYHHMN5Qia/k7/oi/rC/pd/fN8baG+4plzz5rG - q2tfGVdmltXIuEGNMr6sKYhvsNoOei1kaZ3iFfTklfWN4eoy9nxt2aPJHOJqfDXUpQhl - asQ448muZfdFssU34edby/av6VH7fPZJTSXXsrp4Zin6fDZcDWv/s6tg0rKr8OSNkC48 - a6HuVQ+qfWqL2gpNPaa2q21qF9+OqgPlHcOclYkLrNtl9Sn2YGOa3spJV2aL4N/CL4b/ - pV5hC9c0NPkPTbi5jGkJ3xHcNnCHlP/DX7MDDd4KZW5kc3RyZWFtCmVuZG9iago1MyAw - IG9iago3OTIKZW5kb2JqCjcgMCBvYmoKWyAvSUNDQmFzZWQgNTIgMCBSIF0KZW5kb2Jq - CjI3IDAgb2JqCjw8IC9MZW5ndGggNTQgMCBSIC9GdW5jdGlvblR5cGUgMCAvQml0c1Bl - clNhbXBsZSA4IC9TaXplIFsgMTM2NSBdIC9Eb21haW4KWyAwIDEgXSAvUmFuZ2UgWyAw - IDEgMCAxIDAgMSBdIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4AZXB10IB - AAAAwP//lYoQkTQUGVFpJxqUSjRUKBlf4OHuptO5JmiM/tEI/aFfNEQD1Ec/6Bt9oR76 - RB/oHb2hLuqgV9R2L+gZPaEWekQPqIka6B7doVt0g+qohq5RFV2hS3SBztGZO0Un6BhV - 0BE6RAeojEpoHxVRAeVRDu2hLMqgXbSD0mjbbaFNtIFSaB0l0RpKoDhaRTEURSsogsIo - hJZREAXQElp0C3PMAGm/R/cKZW5kc3RyZWFtCmVuZG9iago1NCAwIG9iagoxNzcKZW5k - b2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9NZWRpYUJveCBbMCAwIDU3NiA3MzNd - IC9Db3VudCAxIC9LaWRzIFsgMiAwIFIgXSA+PgplbmRvYmoKNTUgMCBvYmoKPDwgL1R5 - cGUgL0NhdGFsb2cgL1BhZ2VzIDMgMCBSIC9WZXJzaW9uIC8xLjQgPj4KZW5kb2JqCjU2 - IDAgb2JqCjw8IC9MZW5ndGggNTcgMCBSIC9MZW5ndGgxIDExMjE2IC9GaWx0ZXIgL0Zs - YXRlRGVjb2RlID4+CnN0cmVhbQp4Ab16e2CT1dn4c857zbVJmnuTJmmapOklvdHS0kJj - acu1FahCixTbQrkJWrFWQWFVUaQiE5GL4Jx44TptKBWCDH+MocDmp+gUlKlzn+jcPju3 - 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 - E7K7P73I9SrJBR9L8B0/pLPkgOt3hXmuzwqjlPS7jgWiLCY/S8dSOMV11Pm06/8457te - xbA32bQniD0OuHY7F7s2pEfJ1n7X45KT3e9an0zudOKrB1xLgptccwvl9smbonRvv6sc - 26eHVa7SMo+rxHnelR+IigTLec7JruzC/3Bl4ovYzY2D+sJ6l8O5wTUKm9KdtYFRGA6T - PWQbZJNt/b6Jrlcwi+junxAs2xQl9+wfn1Xoi5Ll4dLxWZuC4wO+4GSXL1gXCGB++klh - lXCTcJ1QJOTgxSY0uEKaYBQNok7UimpRKYqiECU/6a9y8YfJXqhCsuzdL/IifkJ4CSvZ - w+RFufLFgyIrUhFEYzTxCV66JIBbjL0DKGYEMHOAl3N8lLyI35KkqhfDLhR5AqzcoEPJ - w2N7FC8UUEpEChPxBsmjUR4eNHdXWasMY/TldTX/W9Qqt1yJZRP/zyMrcUY24R2GyB5n - M14XwUzC2XylK6ru/8ev607s0FGdk4Oqe39356J58vUXb21HK96CiTzSjdeRetrd7n2L - Oofu9vhb2+cskO5ftHVEOr0dNZFF3hr3vm75Pan6quZ5UnO3t2YfzKu9oWnfvHBHTX93 - uLtWuga0v716acs1c60Znmtp9T+Zq1oabKk0V7v83j/M1SI1t0tztUhztUhztYfb5bkk - EtQubKy+owulE6/I4BWVrMbIhKkzm/AmWHNNlOyQ7s3cCf8Nq6YP6wplbmRzdHJlYW0K - ZW5kb2JqCjU3IDAgb2JqCjc1NjgKZW5kb2JqCjU4IDAgb2JqCjw8IC9UeXBlIC9Gb250 - RGVzY3JpcHRvciAvQXNjZW50IDc3MCAvQ2FwSGVpZ2h0IDcyNyAvRGVzY2VudCAtMjMw - IC9GbGFncyAzMgovRm9udEJCb3ggWy05NTEgLTQ4MSAxNDQ1IDExMjJdIC9Gb250TmFt - ZSAvTlpFUlZQK0hlbHZldGljYSAvSXRhbGljQW5nbGUgMAovU3RlbVYgOTggL01heFdp - ZHRoIDE1MDAgL1N0ZW1IIDg1IC9YSGVpZ2h0IDUzMSAvRm9udEZpbGUyIDU2IDAgUiA+ - PgplbmRvYmoKNTkgMCBvYmoKWyAyNzggMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAw - IDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMAowIDcyMiAwIDAg - MCA3MjIgMjc4IDAgMCAwIDgzMyAwIDAgNjY3IDAgMCA2NjcgNjExIDAgMCAwIDAgMCAw - IDAgMCAwIDAgMCAwCjU1NiA1NTYgNTAwIDU1NiA1NTYgMCA1NTYgNTU2IDIyMiAwIDAg - MjIyIDgzMyA1NTYgNTU2IDU1NiAwIDMzMyA1MDAgMjc4IDU1NgowIDAgMCA1MDAgMCAw - IDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAg - MCAwIDAgMCAwCjAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAw - IDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAKMCAwIDAgMCAwIDAgMCAwIDAg - MCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCA1MDAgXQpl - bmRvYmoKMjYgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1RydWVUeXBlIC9C - YXNlRm9udCAvTlpFUlZQK0hlbHZldGljYSAvRm9udERlc2NyaXB0b3IKNTggMCBSIC9X - aWR0aHMgNTkgMCBSIC9GaXJzdENoYXIgMzIgL0xhc3RDaGFyIDIyMiAvRW5jb2Rpbmcg - L01hY1JvbWFuRW5jb2RpbmcKPj4KZW5kb2JqCjEgMCBvYmoKPDwgL1RpdGxlIChVbnRp - dGxlZCkgL0F1dGhvciAoRG91Z2xhcyBHcmVnb3IpIC9DcmVhdG9yIChPbW5pR3JhZmZs - ZSBQcm9mZXNzaW9uYWwpCi9Qcm9kdWNlciAoTWFjIE9TIFggMTAuNS43IFF1YXJ0eiBQ - REZDb250ZXh0KSAvQ3JlYXRpb25EYXRlIChEOjIwMDkwNjAzMTUyMjEwWjAwJzAwJykK - L01vZERhdGUgKEQ6MjAwOTA2MDMxNTIyMTBaMDAnMDAnKSA+PgplbmRvYmoKeHJlZgow - IDYwCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDA1Njk0NCAwMDAwMCBuIAowMDAwMDAy - MDU1IDAwMDAwIG4gCjAwMDAwNDgyNTAgMDAwMDAgbiAKMDAwMDAwMDAyMiAwMDAwMCBu - IAowMDAwMDAyMDM1IDAwMDAwIG4gCjAwMDAwMDIxNTkgMDAwMDAgbiAKMDAwMDA0Nzg1 - NCAwMDAwMCBuIAowMDAwMDAyNTc4IDAwMDAwIG4gCjAwMDAwMDUzMjEgMDAwMDAgbiAK - MDAwMDAwMjQzMSAwMDAwMCBuIAowMDAwMDA1MzQxIDAwMDAwIG4gCjAwMDAwMDU4OTAg - MDAwMDAgbiAKMDAwMDAwNTkxMCAwMDAwMCBuIAowMDAwMDA2NDU5IDAwMDAwIG4gCjAw - MDAwMDgxODYgMDAwMDAgbiAKMDAwMDAwODczNSAwMDAwMCBuIAowMDAwMDA2NDc5IDAw - MDAwIG4gCjAwMDAwMDcwMjggMDAwMDAgbiAKMDAwMDAwODc1NSAwMDAwMCBuIAowMDAw - MDA5MzA0IDAwMDAwIG4gCjAwMDAwMDcwNDggMDAwMDAgbiAKMDAwMDAwNzU5NyAwMDAw - MCBuIAowMDAwMDA3NjE3IDAwMDAwIG4gCjAwMDAwMDgxNjYgMDAwMDAgbiAKMDAwMDAz - ODc2MCAwMDAwMCBuIAowMDAwMDU2NzY5IDAwMDAwIG4gCjAwMDAwNDc4OTAgMDAwMDAg - biAKMDAwMDA0NjkwMiAwMDAwMCBuIAowMDAwMDA5MzI0IDAwMDAwIG4gCjAwMDAwMTcy - MjYgMDAwMDAgbiAKMDAwMDA0MjgzMSAwMDAwMCBuIAowMDAwMDE3MjQ3IDAwMDAwIG4g - CjAwMDAwMjAxODEgMDAwMDAgbiAKMDAwMDAyOTA2NyAwMDAwMCBuIAowMDAwMDMyMDAx - IDAwMDAwIG4gCjAwMDAwMzQ5NzcgMDAwMDAgbiAKMDAwMDAzNzkxMSAwMDAwMCBuIAow - MDAwMDMyMDIyIDAwMDAwIG4gCjAwMDAwMzQ5NTYgMDAwMDAgbiAKMDAwMDAyNjExMiAw - MDAwMCBuIAowMDAwMDI5MDQ2IDAwMDAwIG4gCjAwMDAwMjAyMDIgMDAwMDAgbiAKMDAw - MDAyMzEzNiAwMDAwMCBuIAowMDAwMDIzMTU3IDAwMDAwIG4gCjAwMDAwMjYwOTEgMDAw - MDAgbiAKMDAwMDAzNzkzMiAwMDAwMCBuIAowMDAwMDM4NzQwIDAwMDAwIG4gCjAwMDAw - Mzg3OTcgMDAwMDAgbiAKMDAwMDA0MjgxMCAwMDAwMCBuIAowMDAwMDQyODY4IDAwMDAw - IG4gCjAwMDAwNDY4ODEgMDAwMDAgbiAKMDAwMDA0NjkzOSAwMDAwMCBuIAowMDAwMDQ3 - ODM0IDAwMDAwIG4gCjAwMDAwNDgyMzAgMDAwMDAgbiAKMDAwMDA0ODMzMyAwMDAwMCBu - IAowMDAwMDQ4Mzk3IDAwMDAwIG4gCjAwMDAwNTYwNTYgMDAwMDAgbiAKMDAwMDA1NjA3 - NyAwMDAwMCBuIAowMDAwMDU2MzEzIDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgNjAg - L1Jvb3QgNTUgMCBSIC9JbmZvIDEgMCBSIC9JRCBbIDxiYzVlZmZkZTlhMWUyZTllZTdk - YTA4ZDUwYzhlZDc4YT4KPGJjNWVmZmRlOWExZTJlOWVlN2RhMDhkNTBjOGVkNzhhPiBd - ID4+CnN0YXJ0eHJlZgo1NzE2NQolJUVPRgoxIDAgb2JqCjw8L0F1dGhvciAoRG91Z2xh - cyBHcmVnb3IpL0NyZWF0aW9uRGF0ZSAoRDoyMDA5MDYwMjE4MTkwMFopL0NyZWF0b3Ig - KE9tbmlHcmFmZmxlIFByb2Zlc3Npb25hbCA1LjEuMSkvTW9kRGF0ZSAoRDoyMDA5MDYw - MzE1MjIwMFopL1Byb2R1Y2VyIChNYWMgT1MgWCAxMC41LjcgUXVhcnR6IFBERkNvbnRl - eHQpL1RpdGxlIChQQ0hMYXlvdXQuZ3JhZmZsZSk+PgplbmRvYmoKeHJlZgoxIDEKMDAw - MDA1ODUyMyAwMDAwMCBuIAp0cmFpbGVyCjw8L0lEIFs8YmM1ZWZmZGU5YTFlMmU5ZWU3 - ZGEwOGQ1MGM4ZWQ3OGE+IDxiYzVlZmZkZTlhMWUyZTllZTdkYTA4ZDUwYzhlZDc4YT5d - IC9JbmZvIDEgMCBSIC9QcmV2IDU3MTY1IC9Sb290IDU1IDAgUiAvU2l6ZSA2MD4+CnN0 - YXJ0eHJlZgo1ODc0MAolJUVPRgo= - - QuickLookThumbnail - - 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 - BAALABcAOwAaYWNzcEFQUEwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPbWAAEAAAAA - 0y1hcHBsiXAwVUVs1ORxbm+PhPb1RwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA - AAAOclhZWgAAASwAAAAUZ1hZWgAAAUAAAAAUYlhZWgAAAVQAAAAUd3RwdAAAAWgAAAAU - Y2hhZAAAAXwAAAAsclRSQwAAAagAAAAOZ1RSQwAAAbgAAAAOYlRSQwAAAcgAAAAOdmNn - dAAAAdgAAAYSbmRpbgAAB+wAAAY+ZGVzYwAADiwAAABkZHNjbQAADpAAAAJCbW1vZAAA - ENQAAAAoY3BydAAAEPwAAAAkWFlaIAAAAAAAAGDoAAA4FAAABlJYWVogAAAAAAAAcDYA - ALICAAAhG1hZWiAAAAAAAAAltwAAFgQAAKu4WFlaIAAAAAAAAPNSAAEAAAABFs9zZjMy - AAAAAAABDEIAAAXe///zJgAAB5IAAP2R///7ov///aMAAAPcAADAbGN1cnYAAAAAAAAA - AQHNAABjdXJ2AAAAAAAAAAEBzQAAY3VydgAAAAAAAAABAc0AAHZjZ3QAAAAAAAAAAAAD - AQAAAgAAACEAcgDsAYICOwMlBFIFqwc3CPcK+A0TDzQRZhOKFZkXixlgGx8cqB4PH2Mg - tSILI2gkySYnJ4so8CpbK78tKS6NL/MxVDKuNAw1XzavOAA5RzqHO788+T4vP2tApEHe - QxdETEWHRr9H9kksSl9LkUzCTfJPIFBOUXRSnlPQVR9WdlfHWRlaa1u2XP5eSF+MYM9i - EmNUZJZl22cdaGFpqmrzbDxtiG7Mb/FxBXIWcyV0N3VJdlt3bHh8eY96n3uxfMJ91X7o - f/qBD4IlgzqEToVdhlaHOYgYiPeJ2Iq7i5yMfo1gjkKPIo//kNqRtZKRk2SUOJUKldmW - qJd0mFCZQ5o8mzWcK50dngue9Z/coL6hnaJ3o06kIqTzpb+mi6dVqByo4qmqqnqra6xl - rV+uWK9NsECxL7Icswaz7bTTtba2mLd2uFS5MroOuuu7ybylvYC+W78zwAnA4cG0wonD - W8QtxQDF08ajx3TIRckWyebKtcuHzFfNKM38zs/Pj9BI0PzRsdJs0ynT59So1WvWMNb3 - 177YhtlP2hba3duk3GrdLt3x3rHfeOBF4Rfh6uK244LkTOUR5dHmj+dI5/3oq+lU6fvq - mus369LsZuz67YruJO7P74bwQPD58bTycPMu8+30sPV39kP3E/fo+Mb5qvqS+4L8ef11 - /nX/UP//AAAAOADDAW4CNgMhBDcFhAbsCHMKHgvXDaoPeRFMExkU1haDGCUZrhslHHAd - sB7xIDQhfiLMJBglaSa6KBIpZCq2LAotXC6oL/AxPTJ8M7w0+zYwN1s4dTmOOqU7vzzX - Pew/AUAUQStCQUNURGhFekaMR55IsUnFStZL50z6ThNPSFCGUb1S9FQsVWBWjle/WO1a - GVtFXHFdm17IX/NhIGJSY4FksWXkZxBoI2kmaiprLGwvbTVuOm8/cEZxTnJXc2J0a3V5 - dol3l3ipeb560nvmfPN98n7hf8mAsoGcgouDdYRihU6GOYciiAeI6onMiq6LiIxijTiO - C47bj6qQfpFzkmSTVZRFlTGWGpcAl+KYwpmemnebTZwhnPKdwJ6On1mgIqDrobaihaN4 - pG6lZqZcp1CoQakvqhurBKvsrNOtt66br3uwXbE9sh2y/rPftMG1oLaEt2a4RrkmugW6 - 5LvAvJy9eb5WvzLADsDrwcnCpsOExGPFQ8YkxwfH68jJyaXKgMtbzDnNGM33ztnPuNCb - 0X3SYNNC1CPVBNXk1sXXo9iB2V7aOdsZ3ATc8N3g3sffsOCW4XniWuM75Brk9uXR5qrn - g+hb6TPqDOrl673sl+1z7lXvQPAx8S7yMvM49Eb1V/Zm93P4evl5+m37U/wr/PX9pf5G - /tn/RP+h//8AAAAkAHwBAgGVAkoDIAQbBSwGWAeWCOEKOQuTDO4OQw+PENESDBMyFEUV - QBYwFyAYEhkJGgQa+xv5HPUd9R7zH/Eg8SHuIugj3yTVJcgmuCenKJEpdypXKzgsEizu - LcYunC9wMEExETHdMqYzbzQ1NPY1uDZ5Nzk39zi0OXE6MDsAO9I8pT14Pk0/Ij/3QM1B - pEJ8Q1VEMUUMRetGykerSI5JcUpUSzlMHUz8TdhOs0+PUGpRSFIkUwFT3lS8VZxWe1db - WEBZJVoKWvJb3VzIXbJeml9+YFdhL2IKYuhjyGSqZY5mdGdcaERpKmoQavZr3GzAbaJu - hG9gcDxxF3H8cu1z43TWdcZ2s3eaeHt5WnoxewV71XyhfWp+LH7sf6uAaYEigduClYNP - hAyEy4WLhkyHDIfNiI+JUYoUitmLoIxqjTWOAY7Pj5+QcZFFkhqS8JPBlISVNpXplp6X - U5gLmMaZhJpHmw2b1pyhnXKeRp8bn/OgzqGoooWjZ6RFpRul7Ka6p4uoZKk/qh2q/qvi - rMutta6gr4ywd7FhskqzMrQZtP213ra7t6C4r7m/utS74rzyvgC/CsASwRvCIMMjxCPF - IcYexxnIE8kNygXK+8vyzPDOOM+T0OvSONOE1NbWL9eN2PTadNwI3bvflOGT47/mP+kX - 7GbwR/Uz+4T//wAAbmRpbgAAAAAAAAY2AACYZQAAWYUAAFMYAACL2gAAJ5oAABVgAABQ - DQAAVDkAAmj1AAIrhQABXCgAAwEAAAIAAAAYADIASgBfAHQAiACcAK4AwgDUAOYA+QEL - AR4BMgFGAVoBbwGFAZwBtAHNAegCBAIiAkICYwKJArEC3wMPA0EDdAOoA9wEEQRHBH8E - twTwBSoFZAWhBd4GHAZcBp0G3wcjB2oHsQf5CEUIkwjhCTEJhQnbCjUKkQrtC00LqwwM - DG4M0g03DZ8OBg5vDtoPRw+1ECYQmBENEYIR+hJ0Eu8TbxPuFHAU6RVbFc4WRRa8FzUX - rhgrGKoZKxmsGjEatxs+G8ccURzdHWgd9R6EHxMfoSAwIMEhUiHjInUjFiPGJH0lNSXw - JqonZigkKOQppipoKy0r8iy7LYMuTC8XL+QwsDF9Mk0zHzP3NOY18Db8OAo5FTomOzc8 - Sj1gPnw/nkDFQetDIURWRZZG2kglSVVKY0t6TJBNrk7ST/9RMFJsU7BU/VZRV69ZGVqH - W/xdfF76YGthnmLVZA1lSmaNZ9ZpJmp8a9dtOW6gcAtxgHL1dHB17XdqeOx6cnv7fY9/ - IYC/glqEAIWmh06I/IqtjF+OFY/RkYeTRpT/lrqYpJqynMCevaC7orCko6aQqH6qa6xd - rlOwTLJMtFS2aLhmulK8O745wDfCSMRrxprI5ctNzc/QeNM31hvZFtuc3fPgT+Ko5P3n - UOmW687t+fAX8h70GfYK9+r5v/uQ/Vn//wAAAA4AIQA1AEkAXABvAIMAlwCrAL8A1ADp - AP4BFAErAUMBWwF1AY8BqwHIAecCBwIpAk0CdAKdAswC/gMzA2gDnwPWBA4ERwSCBL0E - +gU3BXUFtQX3BjkGfQbCBwoHUwefB+oIOgiMCN4JMwmMCegKTAqyCxsLhQvwDF4Mzw1B - DbYOKw6iDxwPlxAVEJURFhGZEh0SoxMsE7cUQRTKFUYVwhZCFsQXRxfLGFIY3RloGfUa - hRsWG6kcPRzUHWoeAh6cHzYfzyBrIQghpSJCIugjoSRiJSMl6CasJ3EoOCkBKcoqlCtf - LCos+C3ELpAvYDAuMPsxyjKbM240TDU9Nj03PjhBOUA6RjtLPFM9Xj5vP4dAo0HBQuxE - GUVRRo9H1kkWSilLSExmTYpOtE/mUR5SXVOkVPNWSFelWQ1aeFvpXWRe3WBQYYZiwWP8 - ZTtmgWfLaRxqc2vObS5ulG/7cWxy3HRRdcd3Pni2ejR7rH0sfq6ANYG9g06E4IZziAmJ - o4s8jNeOc5ASka2TTpTnloKYKZnXm4qdPJ7poJqiSKP8paqnXKkPqsasga4/r/6xxLOM - tVy3Lrjiupi8R74Kv8jBkcNkxTnHE8j3yuDM0M7B0LjSrNSk1qHYmdqM3GvePd/94a3j - XOUD5qHoQuno65btUO8b8QPzEPVR9+77DP//AAAAFgAwAEoAYwB9AJcAsQDNAOkBBgEk - AUQBZQGIAa0B1QH/AiwCXQKTAtEDFQNcA6UD7wQ6BIkE2AUqBX0F0wYrBoUG4gdDB6cI - Dgh5COcJWQnQCk4KzgtVC90MbAz/DZgONA7YD4AQLxDkEZ0SXBMfE+gUsxVuFisW6her - GG4ZNBn7GsQbjhxYHSUd8R6/H40gXCEvIgEi1yO1JJglfiZmJ04oOikoKhcrByv5LO0t - 3i7RL8YwuDGrMqAzmTSZNak2vTfPON457jr9PAw9GT4qPz5AVkFtQopDq0TQRf5HLkhk - SYRKmku0TNNN+U8oUGJRolLxVElVrVcZWJdaHVuoXUNe3GB5Yg5jpmU8ZtZocWoOa6lt - Qm7YcGtx/3OQdR52rHg3ecZ7f31nf0eBKYMChNSGnIhdihiLyY13jyOQx5JwlBOVsZda - mRya6JyxnmigHqHNo3ulH6bCqGWqB6uvrVmvB7C6snO0NLYCt8G5NbqyvCW9qL8lwKjC - McPBxU/G4sh9yhzLws1pzxfQytJ81DPV8det2W/ayNwL3Unejd/d4TDigePN5RbmXOee - 6NvqCest7EjtUu5Y703wPPEf8fzyzPOZ9FD1B/Wu9k727vd8+Af4k/kT+Yn6APp3+tz7 - OfuX+/T8Uvye/OX9Lf10/bz+BP5Y/sL/K/+V//8AAGRlc2MAAAAAAAAACkNvbG9yIExD - RAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA - AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABtbHVjAAAAAAAAABIAAAAMbmJOTwAA - ABIAAADocHRQVAAAABYAAAD6c3ZTRQAAABAAAAEQZmlGSQAAABAAAAEgZGFESwAAABwA - AAEwemhDTgAAAAwAAAFMZnJGUgAAABYAAAFYamFKUAAAAA4AAAFuZW5VUwAAABIAAAF8 - cGxQTAAAABIAAAGOcHRCUgAAABgAAAGgZXNFUwAAABIAAAG4emhUVwAAAA4AAAHKcnVS - VQAAACQAAAHYa29LUgAAAAwAAAH8ZGVERQAAABAAAAIIbmxOTAAAABYAAAIYaXRJVAAA - ABQAAAIuAEYAYQByAGcAZQAtAEwAQwBEAEwAQwBEACAAYQAgAEMAbwByAGUAcwBGAOQA - cgBnAC0ATABDAEQAVgDkAHIAaQAtAEwAQwBEAEwAQwBEAC0AZgBhAHIAdgBlAHMAawDm - AHIAbV9pgnIAIABMAEMARABMAEMARAAgAGMAbwB1AGwAZQB1AHIwqzDpMPwAIABMAEMA - RABDAG8AbABvAHIAIABMAEMARABLAG8AbABvAHIAIABMAEMARABMAEMARAAgAEMAbwBs - AG8AcgBpAGQAbwBMAEMARAAgAGMAbwBsAG8Acl9pgnJtsmZ2mG95OlZoBCYEMgQ1BEIE - PQQ+BDkAIAQWBBoALQQ0BDgEQQQ/BDsENQQ5zuy37AAgAEwAQwBEAEYAYQByAGIALQBM - AEMARABLAGwAZQB1AHIAZQBuAC0ATABDAEQATABDAEQAIABjAG8AbABvAHIAaQAAbW1v - ZAAAAAAAAAYQAACcgAAAAADDJekAAAAAAAAAAAAAAAAAAAAAAHRleHQAAAAAQ29weXJp - Z2h0IEFwcGxlLCBJbmMuLCAyMDA5AA== - - ReadOnly - NO - RowAlign - 1 - RowSpacing - 36 - SheetTitle - Canvas 1 - SmartAlignmentGuidesActive - YES - SmartDistanceGuidesActive - YES - UniqueID - 1 - UseEntirePage - - VPages - 1 - WindowInfo - - CurrentSheet - 0 - ExpandedCanvases - - - name - Canvas 1 - - - Frame - {{388, 0}, {710, 878}} - ListView - - OutlineWidth - 142 - RightSidebar - - ShowRuler - - Sidebar - - SidebarWidth - 120 - VisibleRegion - {{0, 0}, {561, 709}} - Zoom - 1 - ZoomValues - - - Canvas 1 - 1 - 1 - - - - saveQuickLookFiles - YES - - diff --git a/docs/PCHLayout.png b/docs/PCHLayout.png deleted file mode 100644 index c304e04a05..0000000000 Binary files a/docs/PCHLayout.png and /dev/null differ diff --git a/docs/PTHInternals.html b/docs/PTHInternals.html deleted file mode 100644 index 279d47968b..0000000000 --- a/docs/PTHInternals.html +++ /dev/null @@ -1,177 +0,0 @@ - - - Pretokenized Headers (PTH) - - - - - - - - -
- -

Pretokenized Headers (PTH)

- -

This document first describes the low-level -interface for using PTH and then briefly elaborates on its design and -implementation. If you are interested in the end-user view, please see the -User's Manual.

- - -

Using Pretokenized Headers with clang (Low-level Interface)

- -

The Clang compiler frontend, clang -cc1, supports three command line -options for generating and using PTH files.

- -

To generate PTH files using clang -cc1, use the option --emit-pth: - -

 $ clang -cc1 test.h -emit-pth -o test.h.pth
- -

This option is transparently used by clang when generating PTH -files. Similarly, PTH files can be used as prefix headers using the --include-pth option:

- -
-  $ clang -cc1 -include-pth test.h.pth test.c -o test.s
-
- -

Alternatively, Clang's PTH files can be used as a raw "token-cache" -(or "content" cache) of the source included by the original header -file. This means that the contents of the PTH file are searched as substitutes -for any source files that are used by clang -cc1 to process a -source file. This is done by specifying the -token-cache -option:

- -
-  $ cat test.h
-  #include <stdio.h>
-  $ clang -cc1 -emit-pth test.h -o test.h.pth
-  $ cat test.c
-  #include "test.h"
-  $ clang -cc1 test.c -o test -token-cache test.h.pth
-
- -

In this example the contents of stdio.h (and the files it includes) -will be retrieved from test.h.pth, as the PTH file is being used in -this case as a raw cache of the contents of test.h. This is a low-level -interface used to both implement the high-level PTH interface as well as to -provide alternative means to use PTH-style caching.

- -

PTH Design and Implementation

- -

Unlike GCC's precompiled headers, which cache the full ASTs and preprocessor -state of a header file, Clang's pretokenized header files mainly cache the raw -lexer tokens that are needed to segment the stream of characters in a -source file into keywords, identifiers, and operators. Consequently, PTH serves -to mainly directly speed up the lexing and preprocessing of a source file, while -parsing and type-checking must be completely redone every time a PTH file is -used.

- -

Basic Design Tradeoffs

- -

In the long term there are plans to provide an alternate PCH implementation -for Clang that also caches the work for parsing and type checking the contents -of header files. The current implementation of PCH in Clang as pretokenized -header files was motivated by the following factors:

- -

    - -

  • Language independence: PTH files work with any language that -Clang's lexer can handle, including C, Objective-C, and (in the early stages) -C++. This means development on language features at the parsing level or above -(which is basically almost all interesting pieces) does not require PTH to be -modified.

    • - -
  • Simple design: Relatively speaking, PTH has a simple design and -implementation, making it easy to test. Further, because the machinery for PTH -resides at the lower-levels of the Clang library stack it is fairly -straightforward to profile and optimize.
    • -
- -

Further, compared to GCC's PCH implementation (which is the dominate -precompiled header file implementation that Clang can be directly compared -against) the PTH design in Clang yields several attractive features:

- -
    - -

  • Architecture independence: In contrast to GCC's PCH files (and -those of several other compilers), Clang's PTH files are architecture -independent, requiring only a single PTH file when building an program for -multiple architectures.

    - -

    For example, on Mac OS X one may wish to -compile a "universal binary" that runs on PowerPC, 32-bit Intel -(i386), and 64-bit Intel architectures. In contrast, GCC requires a PCH file for -each architecture, as the definitions of types in the AST are -architecture-specific. Since a Clang PTH file essentially represents a lexical -cache of header files, a single PTH file can be safely used when compiling for -multiple architectures. This can also reduce compile times because only a single -PTH file needs to be generated during a build instead of several.

    • - -

  • Reduced memory pressure: Similar to GCC, -Clang reads PTH files via the use of memory mapping (i.e., mmap). -Clang, however, memory maps PTH files as read-only, meaning that multiple -invocations of clang -cc1 can share the same pages in memory from a -memory-mapped PTH file. In comparison, GCC also memory maps its PCH files but -also modifies those pages in memory, incurring the copy-on-write costs. The -read-only nature of PTH can greatly reduce memory pressure for builds involving -multiple cores, thus improving overall scalability.

    • - -

  • Fast generation: PTH files can be generated in a small fraction -of the time needed to generate GCC's PCH files. Since PTH/PCH generation is a -serial operation that typically blocks progress during a build, faster -generation time leads to improved processor utilization with parallel builds on -multicore machines.

    • - -
- -

Despite these strengths, PTH's simple design suffers some algorithmic -handicaps compared to other PCH strategies such as those used by GCC. While PTH -can greatly speed up the processing time of a header file, the amount of work -required to process a header file is still roughly linear in the size of the -header file. In contrast, the amount of work done by GCC to process a -precompiled header is (theoretically) constant (the ASTs for the header are -literally memory mapped into the compiler). This means that only the pieces of -the header file that are referenced by the source file including the header are -the only ones the compiler needs to process during actual compilation. While -GCC's particular implementation of PCH mitigates some of these algorithmic -strengths via the use of copy-on-write pages, the approach itself can -fundamentally dominate at an algorithmic level, especially when one considers -header files of arbitrary size.

- -

There are plans to potentially implement an complementary PCH implementation -for Clang based on the lazy deserialization of ASTs. This approach would -theoretically have the same constant-time algorithmic advantages just mentioned -but would also retain some of the strengths of PTH such as reduced memory -pressure (ideal for multi-core builds).

- -

Internal PTH Optimizations

- -

While the main optimization employed by PTH is to reduce lexing time of -header files by caching pre-lexed tokens, PTH also employs several other -optimizations to speed up the processing of header files:

- -
    - -

  • stat caching: PTH files cache information obtained via -calls to stat that clang -cc1 uses to resolve which files are -included by #include directives. This greatly reduces the overhead -involved in context-switching to the kernel to resolve included files.

    • - -

  • Fasting skipping of #ifdef...#endif chains: -PTH files record the basic structure of nested preprocessor blocks. When the -condition of the preprocessor block is false, all of its tokens are immediately -skipped instead of requiring them to be handled by Clang's -preprocessor.

    • - -
- -
- - diff --git a/docs/UsersManual.html b/docs/UsersManual.html deleted file mode 100644 index 4ba00e0b9a..0000000000 --- a/docs/UsersManual.html +++ /dev/null @@ -1,904 +0,0 @@ - - -Clang Compiler User's Manual - - - - - - - - -
- -

Clang Compiler User's Manual

- - - - - -

Introduction

- - -

The Clang Compiler is an open-source compiler for the C family of programming -languages, aiming to be the best in class implementation of these languages. -Clang builds on the LLVM optimizer and code generator, allowing it to provide -high-quality optimization and code generation support for many targets. For -more general information, please see the Clang -Web Site or the LLVM Web Site.

- -

This document describes important notes about using Clang as a compiler for -an end-user, documenting the supported features, command line options, etc. If -you are interested in using Clang to build a tool that processes code, please -see the Clang Internals Manual. If you are -interested in the Clang -Static Analyzer, please see its web page.

- -

Clang is designed to support the C family of programming languages, which -includes C, Objective-C, C++, and Objective-C++ as well as many -dialects of those. For language-specific information, please see the -corresponding language specific section:

- - - -

In addition to these base languages and their dialects, Clang supports a -broad variety of language extensions, which are documented in the corresponding -language section. These extensions are provided to be compatible with the GCC, -Microsoft, and other popular compilers as well as to improve functionality -through Clang-specific features. The Clang driver and language features are -intentionally designed to be as compatible with the GNU GCC compiler as -reasonably possible, easing migration from GCC to Clang. In most cases, code -"just works".

- -

In addition to language specific features, Clang has a variety of features -that depend on what CPU architecture or operating system is being compiled for. -Please see the Target-Specific Features and -Limitations section for more details.

- -

The rest of the introduction introduces some basic compiler terminology that is used throughout this manual -and contains a basic introduction to using Clang -as a command line compiler.

- - -

Terminology

- - -

Front end, parser, backend, preprocessor, undefined behavior, diagnostic, - optimizer

- - -

Basic Usage

- - -

Intro to how to use a C compiler for newbies.

-

-compile + link - -compile then link - -debug info - -enabling optimizations - -picking a language to use, defaults to C99 by default. Autosenses based on -extension. - -using a makefile -

- - - -

Command Line Options

- - -

-This section is generally an index into other sections. It does not go into -depth on the ones that are covered by other sections. However, the first part -introduces the language selection and other high level options like -c, -g, etc. -

- - - -

Options to Control Error and Warning Messages

- - -

-Werror: Turn warnings into errors.

-

-Werror=foo: Turn warning "foo" into an error.

-

-Wno-error=foo: Turn warning "foo" into an warning even if -Werror is - specified.

-

-Wfoo: Enable warning foo

-

-Wno-foo: Disable warning foo

-

-w: Disable all warnings.

-

-pedantic: Warn on language extensions.

-

-pedantic-errors: Error on language extensions.

-

-Wsystem-headers: Enable warnings from system headers.

- -

-ferror-limit=123: Stop emitting diagnostics after 123 errors have - been produced. The default is 20, and the error limit can be disabled with - -ferror-limit=0.

- -

-ftemplate-backtrace-limit=123: Only emit up to 123 template instantiation notes within the template instantiation backtrace for a single warning or error. The default is 10, and the limit can be disabled with -ftemplate-backtrace-limit=0.

- - -

Formatting of Diagnostics

- - -

Clang aims to produce beautiful diagnostics by default, particularly for new -users that first come to Clang. However, different people have different -preferences, and sometimes Clang is driven by another program that wants to -parse simple and consistent output, not a person. For these cases, Clang -provides a wide range of options to control the exact output format of the -diagnostics that it generates.

- -
- - -
-f[no-]show-column: Print column number in -diagnostic.
-
This option, which defaults to on, controls whether or not Clang prints the -column number of a diagnostic. For example, when this is enabled, Clang will -print something like:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-  #endif bad
-         ^
-         //
-
- -

When this is disabled, Clang will print "test.c:28: warning..." with no -column number.

-
- - -
-f[no-]show-source-location: Print -source file/line/column information in diagnostic.
-
This option, which defaults to on, controls whether or not Clang prints the -filename, line number and column number of a diagnostic. For example, -when this is enabled, Clang will print something like:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-  #endif bad
-         ^
-         //
-
- -

When this is disabled, Clang will not print the "test.c:28:8: " part.

-
- - -
-f[no-]caret-diagnostics: Print source -line and ranges from source code in diagnostic.
-
This option, which defaults to on, controls whether or not Clang prints the -source line, source ranges, and caret when emitting a diagnostic. For example, -when this is enabled, Clang will print something like:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-  #endif bad
-         ^
-         //
-
- -

When this is disabled, Clang will just print:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-
- -
- - -
-f[no-]diagnostics-show-option: -Enable [-Woption] information in diagnostic line.
-
This option, which defaults to on, -controls whether or not Clang prints the associated warning group option name when outputting -a warning diagnostic. For example, in this output:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-  #endif bad
-         ^
-         //
-
- -

Passing -fno-diagnostics-show-option will prevent Clang from printing -the [-Wextra-tokens] information in the -diagnostic. This information tells you the flag needed to enable or disable the -diagnostic, either from the command line or through #pragma GCC diagnostic.

- - -
-fdiagnostics-show-category=none/id/name: -Enable printing category information in diagnostic line.
-
This option, which defaults to "none", -controls whether or not Clang prints the category associated with a diagnostic -when emitting it. Each diagnostic may or many not have an associated category, -if it has one, it is listed in the diagnostic categorization field of the -diagnostic line (in the []'s).

- -

For example, a format string warning will produce these three renditions -based on the setting of this option:

- -
-  t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
-  t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
-  t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
-
- -

This category can be used by clients that want to group diagnostics by -category, so it should be a high level category. We want dozens of these, not -hundreds or thousands of them.

-
- - - - -
-f[no-]diagnostics-fixit-info: -Enable "FixIt" information in the diagnostics output.
-
This option, which defaults to on, controls whether or not Clang prints the -information on how to fix a specific diagnostic underneath it when it knows. -For example, in this output:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-  #endif bad
-         ^
-         //
-
- -

Passing -fno-diagnostics-fixit-info will prevent Clang from printing -the "//" line at the end of the message. This information is useful for users -who may not understand what is wrong, but can be confusing for machine -parsing.

-
- - -
--f[no-]diagnostics-print-source-range-info: -Print machine parsable information about source ranges.
-
This option, which defaults to off, controls whether or not Clang prints -information about source ranges in a machine parsable format after the -file/line/column number information. The information is a simple sequence of -brace enclosed ranges, where each range lists the start and end line/column -locations. For example, in this output:

- -
-exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
-   P = (P-42) + Gamma*4;
-       ~~~~~~ ^ ~~~~~~~
-
- -

The {}'s are generated by -fdiagnostics-print-source-range-info.

-
- - -
- - - - - -

Individual Warning Groups

- - -

TODO: Generate this from tblgen. Define one anchor per warning group.

- - -
- - - -
-Wextra-tokens: Warn about excess tokens at - the end of a preprocessor directive.
-
This option, which defaults to on, enables warnings about extra tokens at -the end of preprocessor directives. For example:

- -
-  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
-  #endif bad
-         ^
-
- -

These extra tokens are not strictly conforming, and are usually best handled -by commenting them out.

- -

This option is also enabled by -Wfoo, -Wbar, - and -Wbaz.

-
- -
- - -

Language and Target-Independent Features

- - - - -

Controlling Errors and Warnings

- - -

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 -the ability to print this information, and these are the options that control -it:

- -

-

    -
  1. A file/line/column indicator that shows exactly where the diagnostic occurs - in your code [-fshow-column, -fshow-source-location].
    2. -
  2. A categorization of the diagnostic as a note, warning, error, or fatal - error.
    3. -
  3. A text string that describes what the problem is.
    4. -
  4. An option that indicates how to control the diagnostic (for diagnostics that - support it) [-fdiagnostics-show-option].
    5. -
  5. A high-level category for the diagnostic for clients that want to group - diagnostics by class (for diagnostics that - support it) [-fdiagnostics-show-category].
    6. -
  6. The line of source code that the issue occurs on, along with a caret and - ranges that indicate the important locations [-fcaret-diagnostics].
    7. -
  7. "FixIt" information, which is a concise explanation of how to fix the - problem (when Clang is certain it knows) [-fdiagnostics-fixit-info].
    8. -
  8. A machine-parsable representation of the ranges involved (off by - default) [-fdiagnostics-print-source-range-info].
    9. -

- -

For more information please see Formatting of -Diagnostics.

- -

Diagnostic Mappings

- -

All diagnostics are mapped into one of these 5 classes:

- -

-

    -
  • Ignored
    • -
  • Note
    • -
  • Warning
    • -
  • Error
    • -
  • Fatal
    • -

- -

Controlling Diagnostics via Command Line Flags

- -

-W flags, -pedantic, etc

- -

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:

- -
-#pragma GCC diagnostic ignored "-Wall"
-
- -

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.

- -
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wmultichar"
-
-char b = 'df'; // no warning.
-
-#pragma clang diagnostic pop
-
- -

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

- - -

Precompiled -headers are a general approach employed by many compilers to reduce -compilation time. The underlying motivation of the approach is that it is -common for the same (and often large) header files to be included by -multiple source files. Consequently, compile times can often be greatly improved -by caching some of the (redundant) work done by a compiler to process headers. -Precompiled header files, which represent one of many ways to implement -this optimization, are literally files that represent an on-disk cache that -contains the vital information necessary to reduce some of the work -needed to process a corresponding header file. While details of precompiled -headers vary between compilers, precompiled headers have been shown to be a -highly effective at speeding up program compilation on systems with very large -system headers (e.g., Mac OS/X).

- -

Generating a PCH File

- -

To generate a PCH file using Clang, one invokes Clang with -the -x <language>-header option. This mirrors the -interface in GCC for generating PCH files:

- -
-  $ gcc -x c-header test.h -o test.h.gch
-  $ clang -x c-header test.h -o test.h.pch
-
- -

Using a PCH File

- -

A PCH file can then be used as a prefix header when a --include option is passed to clang:

- -
-  $ clang -include test.h test.c -o test
-
- -

The clang driver will first check if a PCH file for test.h -is available; if so, the contents of test.h (and the files it includes) -will be processed from the PCH file. Otherwise, Clang falls back to -directly processing the content of test.h. This mirrors the behavior of -GCC.

- -

NOTE: Clang does not automatically use PCH files -for headers that are directly included within a source file. For example:

- -
-  $ clang -x c-header test.h -o test.h.pch
-  $ cat test.c
-  #include "test.h"
-  $ clang test.c -o test
-
- -

In this example, clang will not automatically use the PCH file for -test.h since test.h was included directly in the source file -and not specified on the command line using -include.

- -

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:

- -
-  # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
-
- -

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.

- - -

Controlling Code Generation

- - -

Clang provides a number of ways to control code generation. The options are listed below.

- - -
-fcatch-undefined-behavior: Turn -on runtime code generation to check for undefined behavior.
- -
This option, which defaults to off, controls whether or not Clang -adds runtime checks for undefined runtime behavior. If the check fails, -__builtin_trap() is used to indicate failure. -The checks are: -

-

  • Subscripting where the static type of one operand is variable - which is decayed from an array type and the other operand is - greater than the size of the array or less than zero.
    • -
  • Shift operators where the amount shifted is greater or equal to the - promoted bit-width of the left-hand-side or less than zero.
    • -
  • If control flow reaches __builtin_unreachable. -
  • When llvm implements more __builtin_object_size support, reads and - writes for objects that __builtin_object_size indicates we aren't - accessing valid memory. Bit-fields and vectors are not yet checked. -

    -
    • - -
    -fno-assume-sane-operator-new: -Don't assume that the C++'s new operator is sane.
    -
    This option tells the compiler to do not assume that C++'s global new -operator will always return a pointer that do not -alias any other pointer when the function returns.
    - - -

    C Language Features

    - - -

    The support for standard C in clang is feature-complete except for the C99 -floating-point pragmas.

    - - -

    Extensions supported by clang

    - - -

    See clang language extensions.

    - - -

    Differences between various standard modes

    - - -

    clang supports the -std option, which changes what language mode clang uses. -The supported modes for C are c89, gnu89, c94, c99, gnu99 and various aliases -for those modes. If no -std option is specified, clang defaults to gnu99 mode. -

    - -

    Differences between all c* and gnu* modes:

    -
      -
    • c* modes define "__STRICT_ANSI__".
      • -
    • Target-specific defines not prefixed by underscores, like "linux", are -defined in gnu* modes.
      • -
    • Trigraphs default to being off in gnu* modes; they can be enabled by the --trigraphs option.
      • -
    • The parser recognizes "asm" and "typeof" as keywords in gnu* modes; the -variants "__asm__" and "__typeof__" are recognized in all modes.
      • -
    • The Apple "blocks" extension is recognized by default in gnu* modes -on some platforms; it can be enabled in any mode with the "-fblocks" -option.
      • -
    - -

    Differences between *89 and *99 modes:

    -
      -
    • The *99 modes default to implementing "inline" as specified in C99, while -the *89 modes implement the GNU version. This can be overridden for individual -functions with the __gnu_inline__ attribute.
      • -
    • Digraphs are not recognized in c89 mode.
      • -
    • The scope of names defined inside a "for", "if", "switch", "while", or "do" -statement is different. (example: "if ((struct x {int x;}*)0) {}".)
      • -
    • __STDC_VERSION__ is not defined in *89 modes.
      • -
    • "inline" is not recognized as a keyword in c89 mode.
      • -
    • "restrict" is not recognized as a keyword in *89 modes.
      • -
    • Commas are allowed in integer constant expressions in *99 modes.
      • -
    • Arrays which are not lvalues are not implicitly promoted to pointers in -*89 modes.
      • -
    • Some warnings are different.
      • -
    - -

    c94 mode is identical to c89 mode except that digraphs are enabled in -c94 mode (FIXME: And __STDC_VERSION__ should be defined!).

    - - -

    GCC extensions not implemented yet

    - - -

    clang tries to be compatible with gcc as much as possible, but some gcc -extensions are not implemented yet:

    - -
      -
    • clang does not support __label__ -(bug 3429). This is -a relatively small feature, so it is likely to be implemented relatively -soon.
      • - -
    • clang does not support attributes on function pointers -(bug 2461). This is -a relatively important feature, so it is likely to be implemented relatively -soon.
      • - -
    • clang does not support #pragma weak -(bug 3679). Due to -the uses described in the bug, this is likely to be implemented at some -point, at least partially.
      • - -
    • clang does not support #pragma align -(bug 3811). This is a -relatively small feature, so it is likely to be implemented relatively -soon.
      • - -
    • clang does not support code generation for local variables pinned to -registers (bug 3933). -This is a relatively small feature, so it is likely to be implemented -relatively soon.
      • - -
    • clang does not support decimal floating point types (_Decimal32 and -friends) or fixed-point types (_Fract and friends); nobody has expressed -interest in these features yet, so it's hard to say when they will be -implemented.
      • - -
    • clang does not support nested functions; this is a complex feature which -is infrequently used, so it is unlikely to be implemented anytime soon.
      • - -
    • clang does not support global register variables, this is unlikely -to be implemented soon because it requires additional LLVM backend support. -
      • - -
    • clang does not support static initialization of flexible array -members. This appears to be a rarely used extension, but could be -implemented pending user demand.
      • - -
    • clang does not support __builtin_va_arg_pack/__builtin_va_arg_pack_len. -This is used rarely, but in some potentially interesting places, like the -glibc headers, so it may be implemented pending user demand. Note that -because clang pretends to be like GCC 4.2, and this extension was introduced -in 4.3, the glibc headers will not try to use this extension with clang at -the moment.
      • - -
    • clang does not support the gcc extension for forward-declaring function -parameters; this has not showed up in any real-world code yet, though, so it -might never be implemented.
      • - -
    - -

    This is not a complete list; if you find an unsupported extension -missing from this list, please send an e-mail to cfe-dev. This list -currently excludes C++; see C++ Language Features. -Also, this list does not include bugs in mostly-implemented features; please -see the -bug tracker for known existing bugs (FIXME: Is there a section for -bug-reporting guidelines somewhere?).

    - - -

    Intentionally unsupported GCC extensions

    - - -
      - -
    • clang does not support the gcc extension that allows variable-length arrays -in structures. This is for a few of reasons: one, it is tricky -to implement, two, the extension is completely undocumented, and three, the -extension appears to be rarely used.
      • - -
    • clang does not support duplicate definitions of a function where one is -inline. This complicates clients of the AST which normally can expect there is -at most one definition for each function. Source code using this feature should -be changed to define the inline and out-of-line definitions in separate -translation units.
      • - -
    • clang does not have an equivalent to gcc's "fold"; this means that -clang doesn't accept some constructs gcc might accept in contexts where a -constant expression is required, like "x-x" where x is a variable, or calls -to C library functions like strlen.
      • - -
    • clang does not support multiple alternative constraints in inline asm; this -is an extremely obscure feature which would be complicated to implement -correctly.
      • - -
    • clang does not support __builtin_apply and friends; this extension is -extremely obscure and difficult to implement reliably.
      • - -
    - - -

    Microsoft extensions

    - - -

    clang has some experimental support for extensions from -Microsoft Visual C++; to enable it, use the -fms-extensions command-line -option. This is the default for Windows targets. Note that the -support is incomplete; enabling Microsoft extensions will silently drop -certain constructs (including __declspec and Microsoft-style asm statements). -

    - -
  • clang does not support the Microsoft extension where anonymous -record members can be declared using user defined typedefs.
    • - -
  • clang supports the Microsoft "#pragma pack" feature for -controlling record layout. GCC also contains support for this feature, -however where MSVC and GCC are incompatible clang follows the MSVC -definition.
    • - - -

    Objective-C Language Features

    - - - - -

    Intentional Incompatibilities with GCC

    - - -

    No cast of super, no lvalue casts.

    - - - - -

    C++ Language Features

    - - -

    At this point, Clang C++ is not production-quality and is not recommended for use beyond experimentation. However, Clang C++ support -is under active development and is progressing rapidly. Please see the C++ Status page for details or -ask on the mailing list about how you can help.

    - -

    Note that released Clang compilers will refuse to even try to use clang to compile C++ code unless you pass the -ccc-clang-cxx option to the driver. To turn on Clang's C++ support, please pass that flag. Clang compilers built from the Subversion trunk enable C++ support by default, and do not require the -ccc-clang-cxx flag.

    - -

    Clang strives to strictly conform to the C++ standard. That means -it will reject invalid C++ code that another compiler may accept. If -Clang reports errors in your code, please check -the C++ -Compatibility page to see whether they are C++-conformance bugs -and how you can fix them.

    - - -

    Objective C++ Language Features

    - - -

    At this point, Clang C++ support is not generally useful (and therefore, -neither is Objective-C++). Please see the C++ section for -more information.

    - - -

    Target-Specific Features and Limitations

    - - - - -

    CPU Architectures Features and Limitations

    - - - -

    X86

    - -

    The support for X86 (both 32-bit and 64-bit) is considered stable -on Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested to -correctly compile large C and Objective-C codebases. (FIXME: Anything specific -we want to say here? Possibly mention some LLVM x86 limitations?) - - -

    ARM

    - -ARM support is mostly feature-complete, but still experimental; it hasn't -undergone significant testing. - - -

    Other platforms

    - -clang currently contains some support for PPC and Sparc; however, significant -pieces of code generation are still missing, and they haven't undergone -significant testing. - -

    clang contains some support for the embedded PIC16 processor -(FIXME: I haven't been keeping track of this; what should this say?). - -

    clang contains limited support for the MSP430 embedded processor, but both -the clang support and the LLVM backend support are highly experimental. - -

    Other platforms are completely unsupported at the moment. Adding the -minimal support needed for parsing and semantic analysis on a new platform -is quite easy; see lib/Basic/Targets.cpp in the clang source tree. This level -of support is also sufficient for conversion to LLVM IR for simple programs. -Proper support for conversion to LLVM IR requires adding code to -lib/CodeGen/CGCall.cpp at the moment; this is likely to change soon, though. -Generating assembly requires a suitable LLVM backend. - - -

    Operating System Features and Limitations

    - - - -

    Darwin (Mac OS/X)

    - - -

    No __thread support, 64-bit ObjC support requires SL tools.

    - -
    - - diff --git a/docs/api/Makefile b/docs/api/Makefile new file mode 100644 index 0000000000..caeb3d4e4f --- /dev/null +++ b/docs/api/Makefile @@ -0,0 +1,25 @@ +##===- docs/api/Makefile -----------------------------------*- Makefile -*-===## +# +# The LLVM Compiler Infrastructure +# +# This file is distributed under the University of Illinois Open Source +# License. See LICENSE.TXT for details. +# +##===----------------------------------------------------------------------===## + +LEVEL = ../../../.. + +include $(LEVEL)/Makefile.common + +API.Project = clang +API.project = clang +API.srcdir = $(PROJ_SRC_ROOT)/tools/clang + +include $(LLVM_SRC_ROOT)/docs/mk/api.mk + +# Define API.skeleton=1 to generate only a subset of API; for testing purposes. +# +ifneq (undefined,$(origin API.skeleton)) +$(API.doxygen.target): API.doxygen.cfg.opts += INPUT=$(PROJ_SRC_DIR)/intro.h +$(API.doxygen.target): API.doxygen.cfg.opts += INPUT+=$(PROJ_SRC_ROOT)/tools/clang/include/clang/Basic +endif diff --git a/docs/api/api.css b/docs/api/api.css new file mode 100644 index 0000000000..bcc485368b --- /dev/null +++ b/docs/api/api.css @@ -0,0 +1,319 @@ +* { + margin: 0px; + padding: 0px; +} + +body { + padding: 1.0em 2.0em; +} + +body, table { + font-family: Arial, Helvetica, sans-serif; + font-size: 13px; + background-color: #FFFFFF; + color: #000000; +} + +a { + color: #3C7AA0; + text-decoration: none; + font-weight: bold; +} +a:hover { + color: #53A9E8; +} +a.anchor { + color: #000000; +} + +h1 { + font-size: 200%; + text-align: center; +} +h2 { + font-size: 140%; +} +h3 { + font-size: 120%; +} + +h2, h3 { + border-bottom: 2px solid; + margin-top: 2em; +} + +h1, h2, h3 { + margin-bottom: 0.5em; +} + +h3.version { + border: none; + margin-top: 0; + text-align: center; +} + +hr { + display: none; +} + +div.header { +} +div.header div.title { + text-align: center; + font-size: xx-large; + font-weight: bold; +} + +div.footer { + padding-top: 2em; +} +div.footer div { + padding-top: 0.5em; + border-top: 2px solid #000000; +} +div.footer div p { + text-align: right; + font-size: x-small; +} + +div.navigation { + font-size: 9pt; +} +div.navigation div.tabs { + padding-top: 0.5em; + padding-bottom: 0.5em; + border-bottom: 2px solid #000000; +} +div.navigation div.tabs ul { +} +div.navigation div.tabs ul li { + display: inline; + line-height: 200%; +} +div.navigation div.tabs ul li a { + background-color: #183F66; + color: #EEEEEE; + border: 1px solid gray; + border: none; + padding: 0.25em 1.0em; +} +div.navigation div.tabs ul li a { + background: -webkit-gradient(linear, 0% 0%, 0% 100%, from(#3C7AA0), to(#183F66)); + background: -moz-linear-gradient(top, #3C7AA0, #183F66); + -webkit-border-radius: 1.0em; + -moz-border-radius: 1.0em; + -webkit-box-shadow: 0px 1px 2px #777777; + -moz-box-shadow: #777777 0px 1px 2px; +} +div.navigation div.tabs ul li a:hover { + background-color: #2E76CF; + background: -webkit-gradient(linear, 0% 0%, 0% 100%, from(#53A9E8), to(#2E76CF)); + background: -moz-linear-gradient(top, #53A9E8, #2E76CF); + text-shadow: 0px 0px 2px #2F2F2F; +} +div.navigation div.tabs ul li.current a { + color: #F0A000; +} +div.navigation div.tabs ul li.current a:hover { +} + +div.navigation div.navpath { + padding-top: 0.5em; + padding-bottom: 0.5em; + padding-left: 1.0em; + border-bottom: 2px solid #000000; +} + +div.contents { + padding: 1.0em 0.0em; +} + +div.contents p { + margin: 1em 0em; +} + +div.contents dl, +div.contents ul { + margin-top: 1em; + margin-bottom: 1em; + padding-left: 2.0em; + list-style-type: none; +} + +div.contents dl ul, +div.contents ul ul { + margin-top: 0em; + margin-bottom: 0em; +} + +div.center { + text-align:center; +} + +div.dynheader { + padding-top: 1.0em; + padding-bottom: 1.0em; +} + +table { + table-layout: auto; + border-spacing: 0; + border-collapse: collapse; + margin-top: 1.0em; + border-bottom: 1px solid #999999; +} + +table h2 { + border-top: 1px solid #999999; + border-bottom: none; + padding: 0.2em 8px; + margin: 0; + background: #181E29; + color: #FFFFFF; + text-shadow: 0px 0px 2px #000000; + background: -webkit-gradient(linear, 0% 0%, 100% 0%, from(#181E29), to(#868CA8)); + background: -moz-linear-gradient(left, #181E29, #868CA8); +} + +td.indexkey, td.indexvalue { + background-color: #F0F1F2; + border: 1px solid; + padding: 0.4em 0.5em; +} + +td.memTemplParams, td.memItemLeft, td.memItemRight { + border-top: 1px solid #999999; +} +td.memTemplParams, td.memTemplItemLeft, td.memTemplItemRight, td.memItemLeft, td.memItemRight, td.mdescLeft, td.mdescRight { + background-color: #F0F1F2; +} +td.memItemLeft, td.mdescLeft { + padding-left: 0.5em; + padding-left: 0.2em; + border-right: 1px solid #dddddd; +} +td.memItemRight, td.mdescRight { + padding-right: 0.5em; + padding-left: 0.2em; +} + +td div.groupHeader { + border-top: 1px solid #999999; + padding: 0.2em 8px; +} + +td.memItemLeft, td.memItemRight, +td.mdescLeft, td.mdescRight { + padding-top: 0.2em; + padding-bottom: 0.2em; +} + +tr.memlist { + background-color: #F0F1F2; +} +tr.memlist td { + border: 1px solid #999999; + padding: 0.2em 0.5em; +} + +div.memitem { + border: 1px solid #999999; + margin-top: 1.0em; + margin-bottom: 1.0em; + -webkit-border-radius: 0.5em; + -webkit-box-shadow: 3px 3px 6px #777777; + -moz-border-radius: 0.5em; + -moz-box-shadow: black 3px 3px 3px; +} +div.memitem div.memproto { + background-color: #E3E4E5; + padding: 0.25em 0.5em; + -webkit-border-top-left-radius: 0.5em; + -webkit-border-top-right-radius: 0.5em; + -moz-border-radius-topleft: 0.5em; + -moz-border-radius-topright: 0.5em; +} +div.memitem div.memproto td code { + color: #AA0000; +} +div.memitem div.memproto td.paramname code { + color: #000000; +} +div.memitem div.memdoc { + background-color: #F0F1F2; + padding: 0.25em 0.5em; + -webkit-border-bottom-left-radius: 0.5em; + -webkit-border-bottom-right-radius: 0.5em; + -moz-border-radius-bottomleft: 0.5em; + -moz-border-radius-bottomright: 0.5em; +} +div.memitem div.memdoc table { + background-color: #F0F1F2; + border: none; +} + +table.memname { + border: none; + background-color: #E3E4E5; + margin: 0; + padding: 0; +} +td.paramtype { + padding-left: 0.5em; +} +td.paramname { + padding-right: 0.5em; +} + +pre.fragment { + background-color: #F5F5F5; + border: 1px solid #999999; + margin: 1em; + padding: 0.5em; + font-family: monospace, fixed; + font-size: 8pt; + overflow: auto; + word-wrap: break-word; +} +pre.fragment span.keyword { + color: #008000 +} +pre.fragment span.keywordtype { + color: #604020 +} +pre.fragment span.keywordflow { + color: #e08000 +} +pre.fragment span.comment { + color: #800000 +} +pre.fragment span.preprocessor { + color: #806020 +} +pre.fragment span.stringliteral { + color: #002080 +} +pre.fragment span.charliteral { + color: #008080 +} +pre.fragment span.vhdldigit { + color: #ff00ff +} +pre.fragment span.vhdlchar { + color: #000000 +} +pre.fragment span.vhdlkeyword { + color: #700070 +} +pre.fragment span.vhdllogic { + color: #ff0000 +} + +div.contents div.intro div.logo { + background: -webkit-gradient(radial, 50% 50%, 0, 50% 50%, 400, from(#F0A000), to(rgba(24,63,102,0.8))); + background: -moz-radial-gradient(50% 50%, farthest-side, #F0A000, rgba(24,63,102,0.8)); +} + +div.contents div.dynheader { + padding: 0.25em 0.0em; +} diff --git a/docs/api/doxygen.cfg.in b/docs/api/doxygen.cfg.in new file mode 100644 index 0000000000..519fa9830a --- /dev/null +++ b/docs/api/doxygen.cfg.in @@ -0,0 +1,1553 @@ +# Doxyfile 1.6.2 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = clang + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = @version@ + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = @output_dir@ + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = YES + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = @srcdir@ + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = NO + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 2 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it parses. +# With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this tag. +# The format is ext=language, where ext is a file extension, and language is one of +# the parsers supported by doxygen: IDL, Java, Javascript, C#, C, C++, D, PHP, +# Objective-C, Python, Fortran, VHDL, C, C++. For instance to make doxygen treat +# .inc files as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. Note that for custom extensions you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen to replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = NO + +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penality. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will rougly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols + +SYMBOL_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespace are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = YES + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = YES + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the (brief and detailed) documentation of class members so that constructors and destructors are listed first. If set to NO (the default) the constructors will appear in the respective orders defined by SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = YES + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = YES + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or define consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = YES + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. +# This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command , where is the value of +# the FILE_VERSION_FILTER tag, and is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed by +# doxygen. The layout file controls the global structure of the generated output files +# in an output format independent way. The create the layout file that represents +# doxygen's defaults, run doxygen with the -l option. You can optionally specify a +# file name after the option, if omitted DoxygenLayout.xml will be used as the name +# of the layout file. + +LAYOUT_FILE = @srcdir@/docs/api/layout.xml + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = YES + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = NO + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = NO + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = NO + +# This WARN_NO_PARAMDOC option can be abled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = NO + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = @srcdir@/include \ + @srcdir@/lib \ + @srcdir@/docs/api/intro.h + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 + +FILE_PATTERNS = + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = */.svn + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = @srcdir@/examples + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = YES + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command , where +# is the value of the INPUT_FILTER tag, and is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. +# If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. +# Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. +# The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = NO + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. +# Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = YES + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = YES + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 4 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = clang:: + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = html/api + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. + +HTML_HEADER = @srcdir@/docs/api/header.html + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = @srcdir@/docs/api/footer.html + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = NO + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = NO + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and QHP_VIRTUAL_FOLDER +# are set, an additional index file will be generated that can be used as input for +# Qt's qhelpgenerator to generate a Qt Compressed Help (.qch) of the generated +# HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to add. +# For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the custom filter to add.For more information please see +# Qt Help Project / Custom Filters. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this project's +# filter section matches. +# Qt Help Project / Filter Attributes. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + +ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. + +GENERATE_TREEVIEW = NO + +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = NO + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 250 + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be implemented using a PHP enabled web server instead of at the web client using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server based approach is that it scales better to large projects and allows full text search. The disadvances is that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = NO + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include source code with syntax highlighting in the LaTeX output. Note that which sources are shown also depends on other settings such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = NO + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. +# This is useful +# if you want to understand what is going on. +# On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = NO + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# in the INCLUDE_PATH (see below) will be search if a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = YES + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option is superseded by the HAVE_DOT option below. This is only a +# fallback. It is recommended to install and use dot, since it yields more +# powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = NO + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = YES + +# By default doxygen will write a font called FreeSans.ttf to the output +# directory and reference it in all dot files that doxygen generates. This +# font does not include all possible unicode characters however, so when you need +# these (or just want a differently looking font) you can specify the font name +# using DOT_FONTNAME. You need need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# containing the font. + +DOT_FONTNAME = FreeSans + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 9 + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot +# can find it using this tag. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = NO + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = @dot@ + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = YES + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = YES + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/docs/api/footer.html b/docs/api/footer.html new file mode 100644 index 0000000000..000f0978eb --- /dev/null +++ b/docs/api/footer.html @@ -0,0 +1,14 @@ +
    +
    +

    + generated on $datetime for $projectname $projectnumber + by Doxygen $doxygenversion +

    +

    + Copyright © 2003-2010 University of Illinois at Urbana-Champaign. + All Rights Reserved. +

    +
    +
    + + diff --git a/docs/api/header.html b/docs/api/header.html new file mode 100644 index 0000000000..0e8e97dabb --- /dev/null +++ b/docs/api/header.html @@ -0,0 +1,13 @@ + + + + + + + $title + + + + +
    +
    diff --git a/docs/api/intro.h b/docs/api/intro.h new file mode 100644 index 0000000000..6d598310af --- /dev/null +++ b/docs/api/intro.h @@ -0,0 +1,23 @@ +/** @mainpage clang API Documentation +
    + + +@section main_intro Introduction +Welcome to the clang project. + +
    +This documentation describes the internal software that makes +up clang, not the external use of clang. There are no instructions +here on how to use clang, only the APIs that make up the software. For +usage instructions, please see the programmer's guide or reference +manual. + +@section main_caveat Caveat +This documentation is generated directly from the source code with Doxygen. +Since clang is constantly under active development, what you're about to +read is out of date! +
    +*/ diff --git a/docs/api/layout.xml b/docs/api/layout.xml new file mode 100644 index 0000000000..b8df0aa911 --- /dev/null +++ b/docs/api/layout.xml @@ -0,0 +1,184 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/doxygen.cfg b/docs/doxygen.cfg deleted file mode 100644 index 40180b2415..0000000000 --- a/docs/doxygen.cfg +++ /dev/null @@ -1,1230 +0,0 @@ -# Doxyfile 1.4.4 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = clang - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = mainline - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = ../docs/doxygen - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, -# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, -# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, -# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, -# Swedish, and Ukrainian. - -OUTPUT_LANGUAGE = English - -# This tag can be used to specify the encoding used in the generated output. -# The encoding is not always determined by the language that is chosen, -# but also whether or not the output is meant for Windows or non-Windows users. -# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES -# forces the Windows encoding (this is the default for the Windows binary), -# whereas setting the tag to NO uses a Unix-style encoding (the default for -# all platforms other than Windows). - -USE_WINDOWS_ENCODING = NO - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = NO - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = ../.. - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. - -JAVADOC_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. - -DETAILS_AT_TOP = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -#SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 2 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources -# only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = YES - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is YES. - -SHOW_DIRECTORIES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from the -# version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the progam writes to standard output -# is used as the file version. See the manual for examples. - -#FILE_VERSION_FILTER = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = NO - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = NO - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -#WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = ../include \ - ../lib \ - ../docs/doxygen.intro - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = ../examples - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = YES - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = ../docs/img - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = NO - -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -#USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 4 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = llvm:: - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = ../docs/doxygen.header - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = ../docs/doxygen.footer - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = ../docs/doxygen.css - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. - -GENERATE_TREEVIEW = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = letter - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = NO - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_PREDEFINED tags. - -EXPAND_ONLY_PREDEF = NO - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = ../include - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = YES - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = NO - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = YES - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -#GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -#DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = dot - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. - -MAX_DOT_GRAPH_WIDTH = 1024 - -# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. - -MAX_DOT_GRAPH_HEIGHT = 1024 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that a graph may be further truncated if the graph's -# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH -# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), -# the graph is not depth-constrained. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, which results in a white background. -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). - -#DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -#DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -SEARCHENGINE = NO diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in deleted file mode 100644 index c1130fba4e..0000000000 --- a/docs/doxygen.cfg.in +++ /dev/null @@ -1,1230 +0,0 @@ -# Doxyfile 1.4.4 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = clang - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -PROJECT_NUMBER = @PACKAGE_VERSION@ - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = @abs_top_builddir@/docs/doxygen - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, -# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, -# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, -# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, -# Swedish, and Ukrainian. - -OUTPUT_LANGUAGE = English - -# This tag can be used to specify the encoding used in the generated output. -# The encoding is not always determined by the language that is chosen, -# but also whether or not the output is meant for Windows or non-Windows users. -# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES -# forces the Windows encoding (this is the default for the Windows binary), -# whereas setting the tag to NO uses a Unix-style encoding (the default for -# all platforms other than Windows). - -USE_WINDOWS_ENCODING = NO - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = NO - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = NO - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = ../.. - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. - -JAVADOC_AUTOBRIEF = NO - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. - -DETAILS_AT_TOP = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -#SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 2 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources -# only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = YES - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = NO - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = NO - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is YES. - -SHOW_DIRECTORIES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from the -# version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the progam writes to standard output -# is used as the file version. See the manual for examples. - -#FILE_VERSION_FILTER = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = NO - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = NO - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -#WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = @abs_top_srcdir@/include \ - @abs_top_srcdir@/lib \ - @abs_top_srcdir@/docs/doxygen.intro - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm - -FILE_PATTERNS = - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = @abs_top_srcdir@/examples - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = YES - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = @abs_top_srcdir@/docs/img - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = NO - -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -#USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 4 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = clang:: - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. - -HTML_HEADER = @abs_top_srcdir@/docs/doxygen.header - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = @abs_top_srcdir@/docs/doxygen.footer - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = @abs_top_srcdir@/docs/doxygen.css - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. - -GENERATE_TREEVIEW = NO - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. - -LATEX_CMD_NAME = latex - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = makeindex - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = letter - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = NO - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = NO - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = NO - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = NO - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_PREDEFINED tags. - -EXPAND_ONLY_PREDEF = NO - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = ../include - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = YES - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = NO - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = YES - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = YES - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -#GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -#DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = @DOT@ - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. - -MAX_DOT_GRAPH_WIDTH = 1024 - -# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. - -MAX_DOT_GRAPH_HEIGHT = 1024 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that a graph may be further truncated if the graph's -# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH -# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), -# the graph is not depth-constrained. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, which results in a white background. -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). - -#DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. - -#DOT_MULTI_TARGETS = NO - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -SEARCHENGINE = NO diff --git a/docs/doxygen.css b/docs/doxygen.css deleted file mode 100644 index f105e20276..0000000000 --- a/docs/doxygen.css +++ /dev/null @@ -1,378 +0,0 @@ -BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { - font-family: Verdana,Geneva,Arial,Helvetica,sans-serif; -} -BODY,TD { - font-size: 90%; -} -H1 { - text-align: center; - font-size: 140%; - font-weight: bold; -} -H2 { - font-size: 120%; - font-style: italic; -} -H3 { - font-size: 100%; -} -CAPTION { font-weight: bold } -DIV.qindex { - width: 100%; - background-color: #eeeeff; - border: 1px solid #b0b0b0; - text-align: center; - margin: 2px; - padding: 2px; - line-height: 140%; -} -DIV.nav { - width: 100%; - background-color: #eeeeff; - border: 1px solid #b0b0b0; - text-align: center; - margin: 2px; - padding: 2px; - line-height: 140%; -} -DIV.navtab { - background-color: #eeeeff; - border: 1px solid #b0b0b0; - text-align: center; - margin: 2px; - margin-right: 15px; - padding: 2px; -} -TD.navtab { - font-size: 70%; -} -A.qindex { - text-decoration: none; - font-weight: bold; - color: #1A419D; -} -A.qindex:visited { - text-decoration: none; - font-weight: bold; - color: #1A419D -} -A.qindex:hover { - text-decoration: none; - background-color: #ddddff; -} -A.qindexHL { - text-decoration: none; - font-weight: bold; - background-color: #6666cc; - color: #ffffff; - border: 1px double #9295C2; -} -A.qindexHL:hover { - text-decoration: none; - background-color: #6666cc; - color: #ffffff; -} -A.qindexHL:visited { - text-decoration: none; background-color: #6666cc; color: #ffffff } -A.el { text-decoration: none; font-weight: bold } -A.elRef { font-weight: bold } -A.code:link { text-decoration: none; font-weight: normal; color: #0000FF} -A.code:visited { text-decoration: none; font-weight: normal; color: #0000FF} -A.codeRef:link { font-weight: normal; color: #0000FF} -A.codeRef:visited { font-weight: normal; color: #0000FF} -A:hover { text-decoration: none; background-color: #f2f2ff } -DL.el { margin-left: -1cm } -.fragment { - font-family: Fixed, monospace; - font-size: 95%; -} -PRE.fragment { - border: 1px solid #CCCCCC; - background-color: #f5f5f5; - margin-top: 4px; - margin-bottom: 4px; - margin-left: 2px; - margin-right: 8px; - padding-left: 6px; - padding-right: 6px; - padding-top: 4px; - padding-bottom: 4px; -} -DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } -TD.md { background-color: #F4F4FB; font-weight: bold; } -TD.mdPrefix { - background-color: #F4F4FB; - color: #606060; - font-size: 80%; -} -TD.mdname1 { background-color: #F4F4FB; font-weight: bold; color: #602020; } -TD.mdname { background-color: #F4F4FB; font-weight: bold; color: #602020; width: 600px; } -DIV.groupHeader { - margin-left: 16px; - margin-top: 12px; - margin-bottom: 6px; - font-weight: bold; -} -DIV.groupText { margin-left: 16px; font-style: italic; font-size: 90% } -BODY { - background: white; - color: black; - margin-right: 20px; - margin-left: 20px; -} -TD.indexkey { - background-color: #eeeeff; - font-weight: bold; - padding-right : 10px; - padding-top : 2px; - padding-left : 10px; - padding-bottom : 2px; - margin-left : 0px; - margin-right : 0px; - margin-top : 2px; - margin-bottom : 2px; - border: 1px solid #CCCCCC; -} -TD.indexvalue { - background-color: #eeeeff; - font-style: italic; - padding-right : 10px; - padding-top : 2px; - padding-left : 10px; - padding-bottom : 2px; - margin-left : 0px; - margin-right : 0px; - margin-top : 2px; - margin-bottom : 2px; - border: 1px solid #CCCCCC; -} -TR.memlist { - background-color: #f0f0f0; -} -P.formulaDsp { text-align: center; } -IMG.formulaDsp { } -IMG.formulaInl { vertical-align: middle; } -SPAN.keyword { color: #008000 } -SPAN.keywordtype { color: #604020 } -SPAN.keywordflow { color: #e08000 } -SPAN.comment { color: #800000 } -SPAN.preprocessor { color: #806020 } -SPAN.stringliteral { color: #002080 } -SPAN.charliteral { color: #008080 } -.mdTable { - border: 1px solid #868686; - background-color: #F4F4FB; -} -.mdRow { - padding: 8px 10px; -} -.mdescLeft { - padding: 0px 8px 4px 8px; - font-size: 80%; - font-style: italic; - background-color: #FAFAFA; - border-top: 1px none #E0E0E0; - border-right: 1px none #E0E0E0; - border-bottom: 1px none #E0E0E0; - border-left: 1px none #E0E0E0; - margin: 0px; -} -.mdescRight { - padding: 0px 8px 4px 8px; - font-size: 80%; - font-style: italic; - background-color: #FAFAFA; - border-top: 1px none #E0E0E0; - border-right: 1px none #E0E0E0; - border-bottom: 1px none #E0E0E0; - border-left: 1px none #E0E0E0; - margin: 0px; -} -.memItemLeft { - padding: 1px 0px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: solid; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memItemRight { - padding: 1px 8px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: solid; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memTemplItemLeft { - padding: 1px 0px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: none; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memTemplItemRight { - padding: 1px 8px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: none; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - background-color: #FAFAFA; - font-size: 80%; -} -.memTemplParams { - padding: 1px 0px 0px 8px; - margin: 4px; - border-top-width: 1px; - border-right-width: 1px; - border-bottom-width: 1px; - border-left-width: 1px; - border-top-color: #E0E0E0; - border-right-color: #E0E0E0; - border-bottom-color: #E0E0E0; - border-left-color: #E0E0E0; - border-top-style: solid; - border-right-style: none; - border-bottom-style: none; - border-left-style: none; - color: #606060; - background-color: #FAFAFA; - font-size: 80%; -} -.search { color: #003399; - font-weight: bold; -} -FORM.search { - margin-bottom: 0px; - margin-top: 0px; -} -INPUT.search { font-size: 75%; - color: #000080; - font-weight: normal; - background-color: #eeeeff; -} -TD.tiny { font-size: 75%; -} -a { - color: #252E78; -} -a:visited { - color: #3D2185; -} -.dirtab { padding: 4px; - border-collapse: collapse; - border: 1px solid #b0b0b0; -} -TH.dirtab { background: #eeeeff; - font-weight: bold; -} -HR { height: 1px; - border: none; - border-top: 1px solid black; -} - -/* - * LLVM Modifications. - * Note: Everything above here is generated with "doxygen -w htlm" command. See - * "doxygen --help" for details. What follows are CSS overrides for LLVM - * specific formatting. We want to keep the above so it can be replaced with - * subsequent doxygen upgrades. - */ - -.footer { - font-size: 80%; - font-weight: bold; - text-align: center; - vertical-align: middle; -} -.title { - font-size: 25pt; - color: black; background: url("http://llvm.org/img/lines.gif"); - font-weight: bold; - border-width: 1px; - border-style: solid none solid none; - text-align: center; - vertical-align: middle; - padding-left: 8pt; - padding-top: 1px; - padding-bottom: 2px -} -A:link { - cursor: pointer; - text-decoration: none; - font-weight: bolder; -} -A:visited { - cursor: pointer; - text-decoration: underline; - font-weight: bolder; -} -A:hover { - cursor: pointer; - text-decoration: underline; - font-weight: bolder; -} -A:active { - cursor: pointer; - text-decoration: underline; - font-weight: bolder; - font-style: italic; -} -H1 { - text-align: center; - font-size: 140%; - font-weight: bold; -} -H2 { - font-size: 120%; - font-style: italic; -} -H3 { - font-size: 100%; -} -A.qindex {} -A.qindexRef {} -A.el { text-decoration: none; font-weight: bold } -A.elRef { font-weight: bold } -A.code { text-decoration: none; font-weight: normal; color: #4444ee } -A.codeRef { font-weight: normal; color: #4444ee } diff --git a/docs/doxygen.footer b/docs/doxygen.footer deleted file mode 100644 index 524e9a2bb8..0000000000 --- a/docs/doxygen.footer +++ /dev/null @@ -1,10 +0,0 @@ -
    -

    -Generated on $datetime by Doxygen -$doxygenversion.

    - -

    -See the Main Clang Web Page for more -information.

    - - diff --git a/docs/doxygen.header b/docs/doxygen.header deleted file mode 100644 index bea51371ed..0000000000 --- a/docs/doxygen.header +++ /dev/null @@ -1,9 +0,0 @@ - - - - - -clang: $title - - -

    clang API Documentation

    diff --git a/docs/doxygen.intro b/docs/doxygen.intro deleted file mode 100644 index accab72bd0..0000000000 --- a/docs/doxygen.intro +++ /dev/null @@ -1,15 +0,0 @@ -/// @mainpage clang -/// -/// @section main_intro Introduction -/// Welcome to the clang project. -/// -/// This documentation describes the @b internal software that makes -/// up clang, not the @b external use of clang. There are no instructions -/// here on how to use clang, only the APIs that make up the software. For -/// usage instructions, please see the programmer's guide or reference -/// manual. -/// -/// @section main_caveat Caveat -/// This documentation is generated directly from the source code with doxygen. -/// Since clang is constantly under active development, what you're about to -/// read is out of date! diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index d741b68a41..0000000000 --- a/docs/index.html +++ /dev/null @@ -1,4 +0,0 @@ -'clang' C frontend documentation - -None yet, sorry :( - diff --git a/docs/libIndex.html b/docs/libIndex.html deleted file mode 100644 index e722ee14d4..0000000000 --- a/docs/libIndex.html +++ /dev/null @@ -1,267 +0,0 @@ - - - The Index Library - - - - - - - - - -
    - -

    The Index Library

    - -

    Table of Contents

    - - -

    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 -emit-ast t1.c -o t1.ast
-$ clang -emit-ast 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>
-
    -

    - -
    - - - diff --git a/docs/main/AnalyzerRegions.html b/docs/main/AnalyzerRegions.html new file mode 100644 index 0000000000..35708d57c9 --- /dev/null +++ b/docs/main/AnalyzerRegions.html @@ -0,0 +1,258 @@ + + +Static Analyzer Design Document: Memory Regions + + + +

    Static Analyzer Design Document: Memory Regions

    + +

    Authors

    + +

    Ted Kremenek, kremenek at apple
    +Zhongxing Xu, xuzhongzhing at gmail

    + +

    Introduction

    + +

    The path-sensitive analysis engine in libAnalysis employs an extensible API +for abstractly modeling the memory of an analyzed program. This API employs the +concept of "memory regions" to abstractly model chunks of program memory such as +program variables and dynamically allocated memory such as those returned from +'malloc' and 'alloca'. Regions are hierarchical, with subregions modeling +subtyping relationships, field and array offsets into larger chunks of memory, +and so on.

    + +

    The region API consists of two components:

    + +
    • A taxonomy and representation of regions themselves within the analyzer +engine. The primary definitions and interfaces are described in MemRegion.h. +At the root of the region hierarchy is the class MemRegion with +specific subclasses refining the region concept for variables, heap allocated +memory, and so forth.
    • The modeling of binding of values to regions. For +example, modeling the value stored to a local variable x consists of +recording the binding between the region for x (which represents the +raw memory associated with x) and the value stored to x. This +binding relationship is captured with the notion of "symbolic +stores."
    + +

    Symbolic stores, which can be thought of as representing the relation +regions -> values, are implemented by subclasses of the +StoreManager class (Store.h). A +particular StoreManager implementation has complete flexibility concerning the +following: + +

      +
    • How to model the binding between regions and values
      • +
    • What bindings are recorded +
    + +

    Together, both points allow different StoreManagers to tradeoff between +different levels of analysis precision and scalability concerning the reasoning +of program memory. Meanwhile, the core path-sensitive engine makes no +assumptions about either points, and queries a StoreManager about the bindings +to a memory region through a generic interface that all StoreManagers share. If +a particular StoreManager cannot reason about the potential bindings of a given +memory region (e.g., 'BasicStoreManager' does not reason about fields +of structures) then the StoreManager can simply return 'unknown' (represented by +'UnknownVal') for a particular region-binding. This separation of +concerns not only isolates the core analysis engine from the details of +reasoning about program memory but also facilities the option of a client of the +path-sensitive engine to easily swap in different StoreManager implementations +that internally reason about program memory in very different ways. + +

    The rest of this document is divided into two parts. We first discuss region +taxonomy and the semantics of regions. We then discuss the StoreManager +interface, and details of how the currently available StoreManager classes +implement region bindings.

    + +

    Memory Regions and Region Taxonomy

    + +

    Pointers

    + +

    Before talking about the memory regions, we would talk about the pointers +since memory regions are essentially used to represent pointer values.

    + +

    The pointer is a type of values. Pointer values have two semantic aspects. +One is its physical value, which is an address or location. The other is the +type of the memory object residing in the address.

    + +

    Memory regions are designed to abstract these two properties of the pointer. +The physical value of a pointer is represented by MemRegion pointers. The rvalue +type of the region corresponds to the type of the pointee object.

    + +

    One complication is that we could have different view regions on the same +memory chunk. They represent the same memory location, but have different +abstract location, i.e., MemRegion pointers. Thus we need to canonicalize the +abstract locations to get a unique abstract location for one physical +location.

    + +

    Furthermore, these different view regions may or may not represent memory +objects of different types. Some different types are semantically the same, +for example, 'struct s' and 'my_type' are the same type.

    + +
    +struct s;
+typedef struct s my_type;
+
    + +

    But char and int are not the same type in the code below:

    + +
    +void *p;
+int *q = (int*) p;
+char *r = (char*) p;
+
    Thus we need to canonicalize the MemRegion which is used in binding and +retrieving.

    + +

    Regions

    +

    Region is the entity used to model pointer values. A Region has the following +properties:

    + +
      +
    • Kind
      • + +
    • ObjectType: the type of the object residing on the region.
      • + +
    • LocationType: the type of the pointer value that the region corresponds to. + Usually this is the pointer to the ObjectType. But sometimes we want to cache + this type explicitly, for example, for a CodeTextRegion.
      • + +
    • StartLocation
      • + +
    • EndLocation
      • +
    + +

    Symbolic Regions

    + +

    A symbolic region is a map of the concept of symbolic values into the domain +of regions. It is the way that we represent symbolic pointers. Whenever a +symbolic pointer value is needed, a symbolic region is created to represent +it.

    + +

    A symbolic region has no type. It wraps a SymbolData. But sometimes we have +type information associated with a symbolic region. For this case, a +TypedViewRegion is created to layer the type information on top of the symbolic +region. The reason we do not carry type information with the symbolic region is +that the symbolic regions can have no type. To be consistent, we don't let them +to carry type information.

    + +

    Like a symbolic pointer, a symbolic region may be NULL, has unknown extent, +and represents a generic chunk of memory.

    + +

    NOTE: We plan not to use loc::SymbolVal in RegionStore and remove it + gradually.

    + +

    Symbolic regions get their rvalue types through the following ways:

    + +
      +
    • Through the parameter or global variable that points to it, e.g.: +
      +void f(struct s* p) {
+  ...
+}
+
      + +

      The symbolic region pointed to by p has type struct +s.

      • + +
    • Through explicit or implicit casts, e.g.: +
      +void f(void* p) {
+  struct s* q = (struct s*) p;
+  ...
+}
+
      +
      • +
    + +

    We attach the type information to the symbolic region lazily. For the first +case above, we create the TypedViewRegion only when the pointer is +actually used to access the pointee memory object, that is when the element or +field region is created. For the cast case, the TypedViewRegion is +created when visiting the CastExpr.

    + +

    The reason for doing lazy typing is that symbolic regions are sometimes only +used to do location comparison.

    + +

    Pointer Casts

    + +

    Pointer casts allow people to impose different 'views' onto a chunk of +memory.

    + +

    Usually we have two kinds of casts. One kind of casts cast down with in the +type hierarchy. It imposes more specific views onto more generic memory regions. +The other kind of casts cast up with in the type hierarchy. It strips away more +specific views on top of the more generic memory regions.

    + +

    We simulate the down casts by layering another TypedViewRegion on +top of the original region. We simulate the up casts by striping away the top +TypedViewRegion. Down casts is usually simple. For up casts, if the +there is no TypedViewRegion to be stripped, we return the original +region. If the underlying region is of the different type than the cast-to type, +we flag an error state.

    + +

    For toll-free bridging casts, we return the original region.

    + +

    We can set up a partial order for pointer types, with the most general type +void* at the top. The partial order forms a tree with void* as +its root node.

    + +

    Every MemRegion has a root position in the type tree. For example, +the pointee region of void *p has its root position at the root node of +the tree. VarRegion of int x has its root position at the 'int +type' node.

    + +

    TypedViewRegion is used to move the region down or up in the tree. +Moving down in the tree adds a TypedViewRegion. Moving up in the tree +removes a TypedViewRegion.

    + +

    Do we want to allow moving up beyond the root position? This happens +when:

     int x; void *p = &x;
    + +

    The region of x has its root position at 'int*' node. the cast to +void* moves that region up to the 'void*' node. I propose to not allow such +casts, and assign the region of x for p.

    + +

    Another non-ideal case is that people might cast to a non-generic pointer +from another non-generic pointer instead of first casting it back to the generic +pointer. Direct handling of this case would result in multiple layers of +TypedViewRegions. This enforces an incorrect semantic view to the region, +because we can only have one typed view on a region at a time. To avoid this +inconsistency, before casting the region, we strip the TypedViewRegion, then do +the cast. In summary, we only allow one layer of TypedViewRegion.

    + +

    Region Bindings

    + +

    The following region kinds are boundable: VarRegion, CompoundLiteralRegion, +StringRegion, ElementRegion, FieldRegion, and ObjCIvarRegion.

    + +

    When binding regions, we perform canonicalization on element regions and field +regions. This is because we can have different views on the same region, some +of which are essentially the same view with different sugar type names.

    + +

    To canonicalize a region, we get the canonical types for all TypedViewRegions +along the way up to the root region, and make new TypedViewRegions with those +canonical types.

    + +

    For Objective-C and C++, perhaps another canonicalization rule should be +added: for FieldRegion, the least derived class that has the field is used as +the type of the super region of the FieldRegion.

    + +

    All bindings and retrievings are done on the canonicalized regions.

    + +

    Canonicalization is transparent outside the region store manager, and more +specifically, unaware outside the Bind() and Retrieve() method. We don't need to +consider region canonicalization when doing pointer cast.

    + +

    Constraint Manager

    + +

    The constraint manager reasons about the abstract location of memory objects. +We can have different views on a region, but none of these views changes the +location of that object. Thus we should get the same abstract location for those +regions.

    + + + diff --git a/docs/main/Block-ABI-Apple.txt b/docs/main/Block-ABI-Apple.txt new file mode 100644 index 0000000000..dd12036053 --- /dev/null +++ b/docs/main/Block-ABI-Apple.txt @@ -0,0 +1,670 @@ +Block Implementation Specification + +Copyright 2008-2010 Apple, Inc. +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +0. History + +2008/7/14 - created +2008/8/21 - revised, C++ +2008/9/24 - add NULL isa field to __block storage +2008/10/1 - revise block layout to use a static descriptor structure +2008/10/6 - revise block layout to use an unsigned long int flags +2008/10/28 - specify use of _Block_object_assign/dispose for all "Object" types in helper functions +2008/10/30 - revise new layout to have invoke function in same place +2008/10/30 - add __weak support + +2010/3/16 - rev for stret return, signature field +2010/4/6 - improved wording + +This document describes the Apple ABI implementation specification of Blocks. + +The first shipping version of this ABI is found in Mac OS X 10.6, and shall be referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI contract with the runtime and the compiler, and, as necessary, will be referred to as ABI.2010.3.16. + +Since the Apple ABI references symbols from other elements of the system, any attempt to use this ABI on systems prior to SnowLeopard is undefined. + +1. High Level + +The ABI of blocks consist of their layout and the runtime functions required by the compiler. +A Block consists of a structure of the following form: + +struct Block_literal_1 { + void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock + int flags; + int reserved; + void (*invoke)(void *, ...); + struct Block_descriptor_1 { + unsigned long int reserved; // NULL + unsigned long int size; // sizeof(struct Block_literal_1) + // optional helper functions + void (*copy_helper)(void *dst, void *src); // IFF (1<<25) + void (*dispose_helper)(void *src); // IFF (1<<25) + // required ABI.2010.3.16 + const char *signature; // IFF (1<<30) + } *descriptor; + // imported variables +}; + +The following flags bits are in use thusly for a possible ABI.2010.3.16: + +enum { + BLOCK_HAS_COPY_DISPOSE = (1 << 25), + BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code + BLOCK_IS_GLOBAL = (1 << 28), + BLOCK_HAS_STRET = (1 << 29), + BLOCK_HAS_SIGNATURE = (1 << 30), +}; + +In 10.6.ABI the (1<<29) was unconditionally set and ignored by the runtime - it was a transitional marker that did not get deleted after the transition. This bit is now paired with (1<<30), and represented as the pair (3<<30), for the following combinations of valid bit settings, and their meanings. + +switch (flags & (3<<29)) { + case (0<<29): , error + case (1<<29): 10.6.ABI, no signature field available + case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field + case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field, +} + +The following discussions are presented as 10.6.ABI otherwise. + +Block literals may occur within functions where the structure is created in stack local memory. They may also appear as initialization expressions for Block variables of global or static local variables. + +When a Block literal expression is evaluated the stack based structure is initialized as follows: + +1) static descriptor structure is declared and initialized as follows: +1a) the invoke function pointer is set to a function that takes the Block structure as its first argument and the rest of the arguments (if any) to the Block and executes the Block compound statement. +1b) the size field is set to the size of the following Block literal structure. +1c) the copy_helper and dispose_helper function pointers are set to respective helper functions if they are required by the Block literal +2) a stack (or global) Block literal data structure is created and initialized as follows: +2a) the isa field is set to the address of the external _NSConcreteStackBlock, which is a block of uninitialized memory supplied in libSystem, or _NSConcreteGlobalBlock if this is a static or file level block literal. +2) The flags field is set to zero unless there are variables imported into the block that need helper functions for program level Block_copy() and Block_release() operations, in which case the (1<<25) flags bit is set. + + +As an example, the Block literal expression + ^ { printf("hello world\n"); } +would cause to be created on a 32-bit system: + +struct __block_literal_1 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_1 *); + struct __block_descriptor_1 *descriptor; +}; + +void __block_invoke_1(struct __block_literal_1 *_block) { + printf("hello world\n"); +} + +static struct __block_descriptor_1 { + unsigned long int reserved; + unsigned long int Block_size; +} __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 }; + +and where the block literal appeared + + struct __block_literal_1 _block_literal = { + &_NSConcreteStackBlock, + (1<<29), , + __block_invoke_1, + &__block_descriptor_1 + }; + +Blocks import other Block references, const copies of other variables, and variables marked __block. In Objective-C variables may additionally be objects. + +When a Block literal expression used as the initial value of a global or static local variable it is initialized as follows: + struct __block_literal_1 __block_literal_1 = { + &_NSConcreteGlobalBlock, + (1<<28)|(1<<29), , + __block_invoke_1, + &__block_descriptor_1 + }; +that is, a different address is provided as the first value and a particular (1<<28) bit is set in the flags field, and otherwise it is the same as for stack based Block literals. This is an optimization that can be used for any Block literal that imports no const or __block storage variables. + + +2. Imported Variables + +Variables of "auto" storage class are imported as const copies. Variables of "__block" storage class are imported as a pointer to an enclosing data structure. Global variables are simply referenced and not considered as imported. + +2.1 Imported const copy variables + +Automatic storage variables not marked with __block are imported as const copies. + +The simplest example is that of importing a variable of type int. + + int x = 10; + void (^vv)(void) = ^{ printf("x is %d\n", x); } + x = 11; + vv(); + +would be compiled + +struct __block_literal_2 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_2 *); + struct __block_descriptor_2 *descriptor; + const int x; +}; + +void __block_invoke_2(struct __block_literal_2 *_block) { + printf("x is %d\n", _block->x); +} + +static struct __block_descriptor_2 { + unsigned long int reserved; + unsigned long int Block_size; +} __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) }; + +and + + struct __block_literal_2 __block_literal_2 = { + &_NSConcreteStackBlock, + (1<<29), , + __block_invoke_2, + &__block_descriptor_2, + x + }; + +In summary, scalars, structures, unions, and function pointers are generally imported as const copies with no need for helper functions. + +2.2 Imported const copy of Block reference + +The first case where copy and dispose helper functions are required is for the case of when a block itself is imported. In this case both a copy_helper function and a dispose_helper function are needed. The copy_helper function is passed both the existing stack based pointer and the pointer to the new heap version and should call back into the runtime to actually do the copy operation on the imported fields within the block. The runtime functions are all described in Section 5.0 Runtime Helper Functions. + +An example: + + void (^existingBlock)(void) = ...; + void (^vv)(void) = ^{ existingBlock(); } + vv(); + +struct __block_literal_3 { + ...; // existing block +}; + +struct __block_literal_4 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_4 *); + struct __block_literal_3 *const existingBlock; +}; + +void __block_invoke_4(struct __block_literal_2 *_block) { + __block->existingBlock->invoke(__block->existingBlock); +} + +void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) { + //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0); + _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK); +} + +void __block_dispose_4(struct __block_literal_4 *src) { + // was _Block_destroy + _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK); +} + +static struct __block_descriptor_4 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src); + void (*dispose_helper)(struct __block_literal_4 *); +} __block_descriptor_4 = { + 0, + sizeof(struct __block_literal_4), + __block_copy_4, + __block_dispose_4, +}; + +and where it is used + + struct __block_literal_4 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<29), + __block_invoke_4, + & __block_descriptor_4 + existingBlock, + }; + +2.2.1 Importing __attribute__((NSObject)) variables. + +GCC introduces __attribute__((NSObject)) on structure pointers to mean "this is an object". This is useful because many low level data structures are declared as opaque structure pointers, e.g. CFStringRef, CFArrayRef, etc. When used from C, however, these are still really objects and are the second case where that requires copy and dispose helper functions to be generated. The copy helper functions generated by the compiler should use the _Block_object_assign runtime helper function and in the dispose helper the _Block_object_dispose runtime helper function should be called. + +For example, block xyzzy in the following + + struct Opaque *__attribute__((NSObject)) objectPointer = ...; + ... + void (^xyzzy)(void) = ^{ CFPrint(objectPointer); }; + +would have helper functions + +void __block_copy_xyzzy(struct __block_literal_5 *dst, struct __block_literal_5 *src) { + _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT); +} + +void __block_dispose_xyzzy(struct __block_literal_5 *src) { + _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT); +} + +generated. + + +2.3 Imported __block marked variables. + +2.3.1 Layout of __block marked variables + +The compiler must embed variables that are marked __block in a specialized structure of the form: + +struct _block_byref_xxxx { + void *isa; + struct Block_byref *forwarding; + int flags; //refcount; + int size; + typeof(marked_variable) marked_variable; +}; + +Variables of certain types require helper functions for when Block_copy() and Block_release() are performed upon a referencing Block. At the "C" level only variables that are of type Block or ones that have __attribute__((NSObject)) marked require helper functions. In Objective-C objects require helper functions and in C++ stack based objects require helper functions. Variables that require helper functions use the form: + +struct _block_byref_xxxx { + void *isa; + struct _block_byref_xxxx *forwarding; + int flags; //refcount; + int size; + // helper functions called via Block_copy() and Block_release() + void (*byref_keep)(void *dst, void *src); + void (*byref_dispose)(void *); + typeof(marked_variable) marked_variable; +}; + +The structure is initialized such that + a) the forwarding pointer is set to the beginning of its enclosing structure, + b) the size field is initialized to the total size of the enclosing structure, + c) the flags field is set to either 0 if no helper functions are needed or (1<<25) if they are, + d) the helper functions are initialized (if present) + e) the variable itself is set to its initial value. + f) the isa field is set to NULL + +2.3.2 Access to __block variables from within its lexical scope. + +In order to "move" the variable to the heap upon a copy_helper operation the compiler must rewrite access to such a variable to be indirect through the structures forwarding pointer. For example: + + int __block i = 10; + i = 11; + +would be rewritten to be: + + struct _block_byref_i { + void *isa; + struct _block_byref_i *forwarding; + int flags; //refcount; + int size; + int captured_i; + } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 11 }; + + i.forwarding->captured_i = 11; + +In the case of a Block reference variable being marked __block the helper code generated must use the _Block_object_assign and _Block_object_dispose routines supplied by the runtime to make the copies. For example: + + __block void (voidBlock)(void) = blockA; + voidBlock = blockB; + +would translate into + +struct _block_byref_voidBlock { + void *isa; + struct _block_byref_voidBlock *forwarding; + int flags; //refcount; + int size; + void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src); + void (*byref_dispose)(struct _block_byref_voidBlock *); + void (^captured_voidBlock)(void); +}; + +void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { + //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0); + _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); +} + +void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) { + //_Block_destroy(param->captured_voidBlock, 0); + _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)} + +and + struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *), + .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper, + .captured_voidBlock=blockA }; + + voidBlock.forwarding->captured_voidBlock = blockB; + + +2.3.3 Importing __block variables into Blocks + +A Block that uses a __block variable in its compound statement body must import the variable and emit copy_helper and dispose_helper helper functions that, in turn, call back into the runtime to actually copy or release the byref data block using the functions _Block_object_assign and _Block_object_dispose. + +For example: + + int __block i = 2; + functioncall(^{ i = 10; }); + +would translate to + +struct _block_byref_i { + void *isa; // set to NULL + struct _block_byref_voidBlock *forwarding; + int flags; //refcount; + int size; + void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); + void (*byref_dispose)(struct _block_byref_i *); + int captured_i; +}; + + +struct __block_literal_5 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_5 *); + struct __block_descriptor_5 *descriptor; + struct _block_byref_i *i_holder; +}; + +void __block_invoke_5(struct __block_literal_5 *_block) { + _block->forwarding->captured_i = 10; +} + +void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { + //_Block_byref_assign_copy(&dst->captured_i, src->captured_i); + _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); +} + +void __block_dispose_5(struct __block_literal_5 *src) { + //_Block_byref_release(src->captured_i); + _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); +} + +static struct __block_descriptor_5 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); + void (*dispose_helper)(struct __block_literal_5 *); +} __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 }; + +and + + struct _block_byref_i i = {( .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i) )}; + struct __block_literal_5 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<29), , + __block_invoke_5, + &__block_descriptor_5, + 2, + }; + +2.3.4 Importing __attribute__((NSObject)) __block variables + +A __block variable that is also marked __attribute__((NSObject)) should have byref_keep and byref_dispose helper functions that use _Block_object_assign and _Block_object_dispose. + +2.3.5 __block escapes + +Because Blocks referencing __block variables may have Block_copy() performed upon them the underlying storage for the variables may move to the heap. In Objective-C Garbage Collection Only compilation environments the heap used is the garbage collected one and no further action is required. Otherwise the compiler must issue a call to potentially release any heap storage for __block variables at all escapes or terminations of their scope. + + +2.3.6 Nesting + +Blocks may contain Block literal expressions. Any variables used within inner blocks are imported into all enclosing Block scopes even if the variables are not used. This includes const imports as well as __block variables. + +3. Objective C Extensions to Blocks + +3.1 Importing Objects + +Objects should be treated as __attribute__((NSObject)) variables; all copy_helper, dispose_helper, byref_keep, and byref_dispose helper functions should use _Block_object_assign and _Block_object_dispose. There should be no code generated that uses -retain or -release methods. + + +3.2 Blocks as Objects + +The compiler will treat Blocks as objects when synthesizing property setters and getters, will characterize them as objects when generating garbage collection strong and weak layout information in the same manner as objects, and will issue strong and weak write-barrier assignments in the same manner as objects. + +3.3 __weak __block Support + +Objective-C (and Objective-C++) support the __weak attribute on __block variables. Under normal circumstances the compiler uses the Objective-C runtime helper support functions objc_assign_weak and objc_read_weak. Both should continue to be used for all reads and writes of __weak __block variables: + objc_read_weak(&block->byref_i->forwarding->i) + +The __weak variable is stored in a _block_byref_xxxx structure and the Block has copy and dispose helpers for this structure that call: + _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); +and + _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); + + +In turn, the block_byref copy support helpers distinguish between whether the __block variable is a Block or not and should either call: + _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER); +for something declared as an object or + _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); +for something declared as a Block. + +A full example follows: + + + __block __weak id obj = ; + functioncall(^{ [obj somemessage]; }); + +would translate to + +struct _block_byref_obj { + void *isa; // uninitialized + struct _block_byref_obj *forwarding; + int flags; //refcount; + int size; + void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); + void (*byref_dispose)(struct _block_byref_i *); + int captured_obj; +}; + +void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { + //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0); + _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); +} + +void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) { + //_Block_destroy(param->captured_obj, 0); + _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); +}; + +for the block byref part and + +struct __block_literal_5 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_5 *); + struct __block_descriptor_5 *descriptor; + struct _block_byref_obj *byref_obj; +}; + +void __block_invoke_5(struct __block_literal_5 *_block) { + [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage]; +} + +void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { + //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj); + _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); +} + +void __block_dispose_5(struct __block_literal_5 *src) { + //_Block_byref_release(src->byref_obj); + _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); +} + +static struct __block_descriptor_5 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); + void (*dispose_helper)(struct __block_literal_5 *); +} __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 }; + +and within the compound statement: + + struct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj), + .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose, + .captured_obj = )}; + + struct __block_literal_5 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<29), , + __block_invoke_5, + &__block_descriptor_5, + &obj, // a reference to the on-stack structure containing "captured_obj" + }; + + + functioncall(_block_literal->invoke(&_block_literal)); + + +4.0 C++ Support + +Within a block stack based C++ objects are copied as const copies using the const copy constructor. It is an error if a stack based C++ object is used within a block if it does not have a const copy constructor. In addition both copy and destroy helper routines must be synthesized for the block to support the Block_copy() operation, and the flags work marked with the (1<<26) bit in addition to the (1<<25) bit. The copy helper should call the constructor using appropriate offsets of the variable within the supplied stack based block source and heap based destination for all const constructed copies, and similarly should call the destructor in the destroy routine. + +As an example, suppose a C++ class FOO existed with a const copy constructor. Within a code block a stack version of a FOO object is declared and used within a Block literal expression: + +{ + FOO foo; + void (^block)(void) = ^{ printf("%d\n", foo.value()); }; +} + +The compiler would synthesize + +struct __block_literal_10 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_10 *); + struct __block_descriptor_10 *descriptor; + const FOO foo; +}; + +void __block_invoke_10(struct __block_literal_10 *_block) { + printf("%d\n", _block->foo.value()); +} + +void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) { + comp_ctor(&dst->foo, &src->foo); +} + +void __block_dispose_10(struct __block_literal_10 *src) { + comp_dtor(&src->foo); +} + +static struct __block_descriptor_10 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src); + void (*dispose_helper)(struct __block_literal_10 *); +} __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 }; + +and the code would be: +{ + FOO foo; + comp_ctor(&foo); // default constructor + struct __block_literal_10 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<26)|(1<<29), , + __block_invoke_10, + &__block_descriptor_10, + }; + comp_ctor(&_block_literal->foo, &foo); // const copy into stack version + struct __block_literal_10 &block = &_block_literal; // assign literal to block variable + block->invoke(block); // invoke block + comp_dtor(&_block_literal->foo); // destroy stack version of const block copy + comp_dtor(&foo); // destroy original version +} + + +C++ objects stored in __block storage start out on the stack in a block_byref data structure as do other variables. Such objects (if not const objects) must support a regular copy constructor. The block_byref data structure will have copy and destroy helper routines synthesized by the compiler. The copy helper will have code created to perform the copy constructor based on the initial stack block_byref data structure, and will also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper will have code to do the destructor on the object stored within the supplied block_byref heap data structure. + +To support member variable and function access the compiler will synthesize a const pointer to a block version of the this pointer. + +5.0 Runtime Helper Functions + +The runtime helper functions are described in /usr/local/include/Block_private.h. To summarize their use, a block requires copy/dispose helpers if it imports any block variables, __block storage variables, __attribute__((NSObject)) variables, or C++ const copied objects with constructor/destructors. The (1<<26) bit is set and functions are generated. + +The block copy helper function should, for each of the variables of the type mentioned above, call + _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_); +in the copy helper and + _Block_object_dispose(->target, BLOCK_FIELD_); +in the dispose helper where + is + +enum { + BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ... + BLOCK_FIELD_IS_BLOCK = 7, // a block variable + BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable + + BLOCK_FIELD_IS_WEAK = 16, // declared __weak + + BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers +}; + +and of course the CTORs/DTORs for const copied C++ objects. + +The block_byref data structure similarly requires copy/dispose helpers for block variables, __attribute__((NSObject)) variables, or C++ const copied objects with constructor/destructors, and again the (1<<26) bit is set and functions are generated in the same manner. + +Under ObjC we allow __weak as an attribute on __block variables, and this causes the addition of BLOCK_FIELD_IS_WEAK orred onto the BLOCK_FIELD_IS_BYREF flag when copying the block_byref structure in the block copy helper, and onto the BLOCK_FIELD_ field within the block_byref copy/dispose helper calls. + +The prototypes, and summary, of the helper functions are + +/* Certain field types require runtime assistance when being copied to the heap. The following function is used + to copy fields of types: blocks, pointers to byref structures, and objects (including __attribute__((NSObject)) pointers. + BLOCK_FIELD_IS_WEAK is orthogonal to the other choices which are mutually exclusive. + Only in a Block copy helper will one see BLOCK_FIELD_IS_BYREF. + */ +void _Block_object_assign(void *destAddr, const void *object, const int flags); + +/* Similarly a compiler generated dispose helper needs to call back for each field of the byref data structure. + (Currently the implementation only packs one field into the byref structure but in principle there could be more). + The same flags used in the copy helper should be used for each call generated to this function: + */ +void _Block_object_dispose(const void *object, const int flags); + +The following functions have been used and will continue to be supported until new compiler support is complete. + +// Obsolete functions. +// Copy helper callback for copying a block imported into a Block +// Called by copy_helper helper functions synthesized by the compiler. +// The address in the destination block of an imported Block is provided as the first argument +// and the value of the existing imported Block is the second. +// Use: _Block_object_assign(dest, src, BLOCK_FIELD_IS_BLOCK {| BLOCK_FIELD_IS_WEAK}); +void _Block_copy_assign(struct Block_basic **dest, const struct Block_basic *src, const int flags); + +// Destroy helper callback for releasing Blocks imported into a Block +// Called by dispose_helper helper functions synthesized by the compiler. +// The value of the imported Block variable is passed back. +// Use: _Block_object_dispose(src, BLOCK_FIELD_IS_BLOCK {| BLOCK_FIELD_IS_WEAK}); +void _Block_destroy(const struct Block_basic *src, const int flags); + +// Byref data block copy helper callback +// Called by block copy helpers when copying __block structures +// Use: _Block_object_assign(dest, src, BLOCK_FIELD_IS_BYREF {| BLOCK_FIELD_IS_WEAK}); +void _Block_byref_assign_copy(struct Block_byref **destp, struct Block_byref *src); + +// Byref data block release helper callback +// Called by block release helpers when releasing a Block +// Called at escape points in scope where __block variables live (under non-GC-only conditions) +// Use: _Block_object_dispose(src, BLOCK_FIELD_IS_BYREF {| BLOCK_FIELD_IS_WEAK}); +void §(struct Block_byref *shared_struct); + + diff --git a/docs/main/BlockLanguageSpec.txt b/docs/main/BlockLanguageSpec.txt new file mode 100644 index 0000000000..a612fd2889 --- /dev/null +++ b/docs/main/BlockLanguageSpec.txt @@ -0,0 +1,165 @@ +Language Specification for Blocks + +2008/2/25 — created +2008/7/28 — revised, __block syntax +2008/8/13 — revised, Block globals +2008/8/21 — revised, C++ elaboration +2008/11/1 — revised, __weak support +2009/1/12 — revised, explicit return types +2009/2/10 — revised, __block objects need retain + +Copyright 2008-2009 Apple, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +The Block Type + +A new derived type is introduced to C and, by extension, Objective-C, C++, and Objective-C++. Like function types, the Block type is a pair consisting of a result value type and a list of parameter types very similar to a function type. Blocks are intended to be used much like functions with the key distinction being that in addition to executable code they also contain various variable bindings to automatic (stack) or managed (heap) memory. + +The abstract declarator int (^)(char, float) describes a reference to a Block that, when invoked, takes two parameters, the first of type char and the second of type float, and returns a value of type int. The Block referenced is of opaque data that may reside in automatic (stack) memory, global memory, or heap memory. + + +Block Variable Declarations + +A variable with Block type is declared using function pointer style notation substituting ^ for *. The following are valid Block variable declarations: + void (^blockReturningVoidWithVoidArgument)(void); + int (^blockReturningIntWithIntAndCharArguments)(int, char); + void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int); + +Variadic ... arguments are supported. [variadic.c] A Block that takes no arguments must specify void in the argument list [voidarg.c]. An empty parameter list does not represent, as K&R provide, an unspecified argument list. Note: both gcc and clang support K&R style as a convenience. + +A Block reference may be cast to a pointer of arbitrary type and vice versa. [cast.c] A Block reference may not be dereferenced via the pointer dereference operator *, and thus a Block's size may not be computed at compile time. [sizeof.c] + + +Block Literal Expressions + +A Block literal expression produces a reference to a Block. It is introduced by the use of the ^ token as a unary operator. + Block_literal_expression ::= ^ block_decl compound_statement_body + block_decl ::= + block_decl ::= parameter_list + block_decl ::= type_expression + +...where type expression is extended to allow ^ as a Block reference (pointer) where * is allowed as a function reference (pointer). + +The following Block literal: + ^ void (void) { printf("hello world\n"); } + +...produces a reference to a Block with no arguments with no return value. + +The return type is optional and is inferred from the return statements. If the return statements return a value, they all must return a value of the same type. If there is no value returned the inferred type of the Block is void; otherwise it is the type of the return statement value. + +If the return type is omitted and the argument list is ( void ), the ( void ) argument list may also be omitted. + +So: + ^ ( void ) { printf("hello world\n"); } + +...and: + ^ { printf("hello world\n"); } + +...are exactly equivalent constructs for the same expression. + +The type_expression extends C expression parsing to accommodate Block reference declarations as it accommodates function pointer declarations. + +Given: + typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char); + pointerToFunctionThatReturnsIntWithCharArg functionPointer; + + ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; } + +...and: + ^ int ((*)(float x))(char) { return functionPointer; } + +...are equivalent expressions, as is: + + ^(float x) { return functionPointer; } + +[returnfunctionptr.c] + +The compound statement body establishes a new lexical scope within that of its parent. Variables used within the scope of the compound statement are bound to the Block in the normal manner with the exception of those in automatic (stack) storage. Thus one may access functions and global variables as one would expect, as well as static local variables. [testme] + +Local automatic (stack) variables referenced within the compound statement of a Block are imported and captured by the Block as const copies. The capture (binding) is performed at the time of the Block literal expression evaluation. + +The lifetime of variables declared in a Block is that of a function; each activation frame contains a new copy of variables declared within the local scope of the Block. Such variable declarations should be allowed anywhere [testme] rather than only when C99 parsing is requested, including for statements. [testme] + +Block literal expressions may occur within Block literal expressions (nest) and all variables captured by any nested blocks are implicitly also captured in the scopes of their enclosing Blocks. + +A Block literal expression may be used as the initialization value for Block variables at global or local static scope. + + +The Invoke Operator + +Blocks are invoked using function call syntax with a list of expression parameters of types corresponding to the declaration and returning a result type also according to the declaration. Given: + int (^x)(char); + void (^z)(void); + int (^(*y))(char) = &x; + +...the following are all legal Block invocations: + x('a'); + (*y)('a'); + (true ? x : *y)('a') + + +The Copy and Release Operations + +The compiler and runtime provide copy and release operations for Block references that create and, in matched use, release allocated storage for referenced Blocks. + +The copy operation Block_copy() is styled as a function that takes an arbitrary Block reference and returns a Block reference of the same type. The release operation, Block_release(), is styled as a function that takes an arbitrary Block reference and, if dynamically matched to a Block copy operation, allows recovery of the referenced allocated memory. + + +The __block Storage Qualifier + +In addition to the new Block type we also introduce a new storage qualifier, __block, for local variables. [testme: a __block declaration within a block literal] The __block storage qualifier is mutually exclusive to the existing local storage qualifiers auto, register, and static.[testme] Variables qualified by __block act as if they were in allocated storage and this storage is automatically recovered after last use of said variable. An implementation may choose an optimization where the storage is initially automatic and only "moved" to allocated (heap) storage upon a Block_copy of a referencing Block. Such variables may be mutated as normal variables are. + +In the case where a __block variable is a Block one must assume that the __block variable resides in allocated storage and as such is assumed to reference a Block that is also in allocated storage (that it is the result of a Block_copy operation). Despite this there is no provision to do a Block_copy or a Block_release if an implementation provides initial automatic storage for Blocks. This is due to the inherent race condition of potentially several threads trying to update the shared variable and the need for synchronization around disposing of older values and copying new ones. Such synchronization is beyond the scope of this language specification. + + +Control Flow + +The compound statement of a Block is treated much like a function body with respect to control flow in that goto, break, and continue do not escape the Block. Exceptions are treated "normally" in that when thrown they pop stack frames until a catch clause is found. + + +Objective-C Extensions + +Objective-C extends the definition of a Block reference type to be that also of id. A variable or expression of Block type may be messaged or used as a parameter wherever an id may be. The converse is also true. Block references may thus appear as properties and are subject to the assign, retain, and copy attribute logic that is reserved for objects. + +All Blocks are constructed to be Objective-C objects regardless of whether the Objective-C runtime is operational in the program or not. Blocks using automatic (stack) memory are objects and may be messaged, although they may not be assigned into __weak locations if garbage collection is enabled. + +Within a Block literal expression within a method definition references to instance variables are also imported into the lexical scope of the compound statement. These variables are implicitly qualified as references from self, and so self is imported as a const copy. The net effect is that instance variables can be mutated. + +The Block_copy operator retains all objects held in variables of automatic storage referenced within the Block expression (or form strong references if running under garbage collection). Object variables of __block storage type are assumed to hold normal pointers with no provision for retain and release messages. + +Foundation defines (and supplies) -copy and -release methods for Blocks. + +In the Objective-C and Objective-C++ languages, we allow the __weak specifier for __block variables of object type. If garbage collection is not enabled, this qualifier causes these variables to be kept without retain messages being sent. This knowingly leads to dangling pointers if the Block (or a copy) outlives the lifetime of this object. + +In garbage collected environments, the __weak variable is set to nil when the object it references is collected, as long as the __block variable resides in the heap (either by default or via Block_copy()). The initial Apple implementation does in fact start __block variables on the stack and migrate them to the heap only as a result of a Block_copy() operation. + +It is a runtime error to attempt to assign a reference to a stack-based Block into any storage marked __weak, including __weak __block variables. + + +C++ Extensions + +Block literal expressions within functions are extended to allow const use of C++ objects, pointers, or references held in automatic storage. + +For example, given class Foo with member function fighter(void): + Foo foo; + Foo &fooRef = foo; + Foo *fooPtr = &foo; + +...a Block that used foo would import the variables as const variations: + const Foo block_foo = foo; // const copy constructor + const Foo &block_fooRef = fooRef; + const Foo *block_fooPtr = fooPtr; + +Stack-local objects are copied into a Block via a copy const constructor. If no such constructor exists, it is considered an error to reference such objects from within the Block compound statements. A destructor is run as control leaves the compound statement that contains the Block literal expression. + +If a Block originates on the stack, a const copy constructor of the stack-based Block const copy is performed when a Block_copy operation is called; when the last Block_release (or subsequently GC) occurs, a destructor is run on the heap copy. + +Variables declared as residing in __block storage may be initially allocated in the heap or may first appear on the stack and be copied to the heap as a result of a Block_copy() operation. When copied from the stack, a normal copy constructor is used to initialize the heap-based version from the original stack version. The destructor for a const copied object is run at the normal end of scope. The destructor for any initial stack based version is also called at normal end of scope. + +Within a member function, access to member functions and variables is done via an implicit const copy of a this pointer. + +Member variables that are Blocks may not be overloaded by the types of their arguments. + diff --git a/docs/main/DriverArchitecture.png b/docs/main/DriverArchitecture.png new file mode 100644 index 0000000000..056a70a98f Binary files /dev/null and b/docs/main/DriverArchitecture.png differ diff --git a/docs/main/DriverInternals.html b/docs/main/DriverInternals.html new file mode 100644 index 0000000000..a7d2da3771 --- /dev/null +++ b/docs/main/DriverInternals.html @@ -0,0 +1,517 @@ + + + Clang Driver Manual + + + + + + + + +
    + +

    Driver Design & Internals

    + + + + + +

    Introduction

    + + +

    This document describes the Clang driver. The purpose of this + document is to describe both the motivation and design goals + for the driver, as well as details of the internal + implementation.

    + + +

    Features and Goals

    + + +

    The Clang driver is intended to be a production quality + compiler driver providing access to the Clang compiler and + tools, with a command line interface which is compatible with + the gcc driver.

    + +

    Although the driver is part of and driven by the Clang + project, it is logically a separate tool which shares many of + the same goals as Clang:

    + +

    Features:

    + + + +

    GCC Compatibility

    + + +

    The number one goal of the driver is to ease the adoption of + Clang by allowing users to drop Clang into a build system + which was designed to call GCC. Although this makes the driver + much more complicated than might otherwise be necessary, we + decided that being very compatible with the gcc command line + interface was worth it in order to allow users to quickly test + clang on their projects.

    + + +

    Flexible

    + + +

    The driver was designed to be flexible and easily accomodate + new uses as we grow the clang and LLVM infrastructure. As one + example, the driver can easily support the introduction of + tools which have an integrated assembler; something we hope to + add to LLVM in the future.

    + +

    Similarly, most of the driver functionality is kept in a + library which can be used to build other tools which want to + implement or accept a gcc like interface.

    + + +

    Low Overhead

    + + +

    The driver should have as little overhead as possible. In + practice, we found that the gcc driver by itself incurred a + small but meaningful overhead when compiling many small + files. The driver doesn't do much work compared to a + compilation, but we have tried to keep it as efficient as + possible by following a few simple principles:

    +
      +
    • Avoid memory allocation and string copying when + possible.
      • + +
    • Don't parse arguments more than once.
      • + +
    • Provide a few simple interfaces for efficiently searching + arguments.
      • +
    + + +

    Simple

    + + +

    Finally, the driver was designed to be "as simple as + possible", given the other goals. Notably, trying to be + completely compatible with the gcc driver adds a significant + amount of complexity. However, the design of the driver + attempts to mitigate this complexity by dividing the process + into a number of independent stages instead of a single + monolithic task.

    + + +

    Internal Design and Implementation

    + + + + + +

    Internals Introduction

    + + +

    In order to satisfy the stated goals, the driver was designed + to completely subsume the functionality of the gcc executable; + that is, the driver should not need to delegate to gcc to + perform subtasks. On Darwin, this implies that the Clang + driver also subsumes the gcc driver-driver, which is used to + implement support for building universal images (binaries and + object files). This also implies that the driver should be + able to call the language specific compilers (e.g. cc1) + directly, which means that it must have enough information to + forward command line arguments to child processes + correctly.

    + + +

    Design Overview

    + + +

    The diagram below shows the significant components of the + driver architecture and how they relate to one another. The + orange components represent concrete data structures built by + the driver, the green components indicate conceptually + distinct stages which manipulate these data structures, and + the blue components are important helper classes.

    + +
    + + + +
    + + +

    Driver Stages

    + + +

    The driver functionality is conceptually divided into five stages:

    + +
      +
    1. + Parse: Option Parsing + +

      The command line argument strings are decomposed into + arguments (Arg instances). The driver expects to + understand all available options, although there is some + facility for just passing certain classes of options + through (like -Wl,).

      + +

      Each argument corresponds to exactly one + abstract Option definition, which describes how + the option is parsed along with some additional + metadata. The Arg instances themselves are lightweight and + merely contain enough information for clients to determine + which option they correspond to and their values (if they + have additional parameters).

      + +

      For example, a command line like "-Ifoo -I foo" would + parse to two Arg instances (a JoinedArg and a SeparateArg + instance), but each would refer to the same Option.

      + +

      Options are lazily created in order to avoid populating + all Option classes when the driver is loaded. Most of the + driver code only needs to deal with options by their + unique ID (e.g., options::OPT_I),

      + +

      Arg instances themselves do not generally store the + values of parameters. In many cases, this would + simply result in creating unnecessary string + copies. Instead, Arg instances are always embedded inside + an ArgList structure, which contains the original vector + of argument strings. Each Arg itself only needs to contain + an index into this vector instead of storing its values + directly.

      + +

      The clang driver can dump the results of this + stage using the -ccc-print-options flag (which + must preceed any actual command line arguments). For + example:

      + 
      +            $ clang -ccc-print-options -Xarch_i386 -fomit-frame-pointer -Wa,-fast -Ifoo -I foo t.c
+            Option 0 - Name: "-Xarch_", Values: {"i386", "-fomit-frame-pointer"}
+            Option 1 - Name: "-Wa,", Values: {"-fast"}
+            Option 2 - Name: "-I", Values: {"foo"}
+            Option 3 - Name: "-I", Values: {"foo"}
+            Option 4 - Name: "<input>", Values: {"t.c"}
+
      + +

      After this stage is complete the command line should be + broken down into well defined option objects with their + appropriate parameters. Subsequent stages should rarely, + if ever, need to do any string processing.

      +
      2. + +
    2. + Pipeline: Compilation Job Construction + +

      Once the arguments are parsed, the tree of subprocess + jobs needed for the desired compilation sequence are + 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 + one or more top-level actions, each of which generally + corresponds to a single output (for example, an object or + linked executable).

      + +

      The majority of Actions correspond to actual tasks, + however there are two special Actions. The first is + InputAction, which simply serves to adapt an input + argument for use as an input to other Actions. The second + is BindArchAction, which conceptually alters the + architecture to be used for all of its input Actions.

      + +

      The clang driver can dump the results of this + stage using the -ccc-print-phases flag. For + example:

      + 
      +            $ clang -ccc-print-phases -x c t.c -x assembler t.s
+            0: input, "t.c", c
+            1: preprocessor, {0}, cpp-output
+            2: compiler, {1}, assembler
+            3: assembler, {2}, object
+            4: input, "t.s", assembler
+            5: assembler, {4}, object
+            6: linker, {3, 5}, image
+
      +

      Here the driver is constructing seven distinct actions, + four to compile the "t.c" input into an object file, two to + assemble the "t.s" input, and one to link them together.

      + +

      A rather different compilation pipeline is shown here; in + this example there are two top level actions to compile + the input files into two separate object files, where each + object file is built using lipo to merge results + built for two separate architectures.

      + 
      +            $ clang -ccc-print-phases -c -arch i386 -arch x86_64 t0.c t1.c
+            0: input, "t0.c", c
+            1: preprocessor, {0}, cpp-output
+            2: compiler, {1}, assembler
+            3: assembler, {2}, object
+            4: bind-arch, "i386", {3}, object
+            5: bind-arch, "x86_64", {3}, object
+            6: lipo, {4, 5}, object
+            7: input, "t1.c", c
+            8: preprocessor, {7}, cpp-output
+            9: compiler, {8}, assembler
+            10: assembler, {9}, object
+            11: bind-arch, "i386", {10}, object
+            12: bind-arch, "x86_64", {10}, object
+            13: lipo, {11, 12}, object
+
      + +

      After this stage is complete the compilation process is + divided into a simple set of actions which need to be + performed to produce intermediate or final outputs (in + some cases, like -fsyntax-only, there is no + "real" final output). Phases are well known compilation + steps, such as "preprocess", "compile", "assemble", + "link", etc.

      +
      3. + +
    3. + Bind: Tool & Filename Selection + +

      This stage (in conjunction with the Translate stage) + turns the tree of Actions into a list of actual subprocess + 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 selected the driver interacts with the tool + to see if it can match additional actions (for example, by + having an integrated preprocessor). + +

      Once Tools have been selected for all actions, the driver + determines how the tools should be connected (for example, + using an inprocess module, pipes, temporary files, or user + provided filenames). If an output file is required, the + driver also computes the appropriate file name (the suffix + and file location depend on the input types and options + such as -save-temps). + +

      The driver interacts with a ToolChain to perform the Tool + bindings. Each ToolChain contains information about all + the tools needed for compilation for a particular + architecture, platform, and operating system. A single + driver invocation may query multiple ToolChains during one + compilation in order to interact with tools for separate + architectures.

      + +

      The results of this stage are not computed directly, but + the driver can print the results via + the -ccc-print-bindings option. For example:

      + 
      +            $ clang -ccc-print-bindings -arch i386 -arch ppc t0.c
+            # "i386-apple-darwin9" - "clang", inputs: ["t0.c"], output: "/tmp/cc-Sn4RKF.s"
+            # "i386-apple-darwin9" - "darwin::Assemble", inputs: ["/tmp/cc-Sn4RKF.s"], output: "/tmp/cc-gvSnbS.o"
+            # "i386-apple-darwin9" - "darwin::Link", inputs: ["/tmp/cc-gvSnbS.o"], output: "/tmp/cc-jgHQxi.out"
+            # "ppc-apple-darwin9" - "gcc::Compile", inputs: ["t0.c"], output: "/tmp/cc-Q0bTox.s"
+            # "ppc-apple-darwin9" - "gcc::Assemble", inputs: ["/tmp/cc-Q0bTox.s"], output: "/tmp/cc-WCdicw.o"
+            # "ppc-apple-darwin9" - "gcc::Link", inputs: ["/tmp/cc-WCdicw.o"], output: "/tmp/cc-HHBEBh.out"
+            # "i386-apple-darwin9" - "darwin::Lipo", inputs: ["/tmp/cc-jgHQxi.out", "/tmp/cc-HHBEBh.out"], output: "a.out"
+
      + +

      This shows the tool chain, tool, inputs and outputs which + have been bound for this compilation sequence. Here clang + is being used to compile t0.c on the i386 architecture and + darwin specific versions of the tools are being used to + assemble and link the result, but generic gcc versions of + the tools are being used on PowerPC.

      +
      4. + +
    4. + Translate: Tool Specific Argument Translation + +

      Once a Tool has been selected to perform a particular + Action, the Tool must construct concrete Jobs which will be + executed during compilation. The main work is in translating + from the gcc style command line options to whatever options + the subprocess expects.

      + +

      Some tools, such as the assembler, only interact with a + handful of arguments and just determine the path of the + executable to call and pass on their input and output + arguments. Others, like the compiler or the linker, may + translate a large number of arguments in addition.

      + +

      The ArgList class provides a number of simple helper + methods to assist with translating arguments; for example, + to pass on only the last of arguments corresponding to some + option, or all arguments for an option.

      + +

      The result of this stage is a list of Jobs (executable + paths and argument strings) to execute.

      +
      5. + +
    5. + Execute +

      Finally, the compilation pipeline is executed. This is + mostly straightforward, although there is some interaction + with options + like -pipe, -pass-exit-codes + and -time.

      +
      6. + +
    + + +

    Additional Notes

    + + +

    The Compilation Object

    + +

    The driver constructs a Compilation object for each set of + command line arguments. The Driver itself is intended to 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.

    + +

    The Compilation object holds information that is particular + to each compilation sequence. For example, the list of used + temporary files (which must be removed once compilation is + finished) and result files (which should be removed if + compilation files).

    + +

    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 + driver.

    + +

    ToolChain Argument Translation

    + +

    In order to match gcc very closely, the clang driver + currently allows tool chains to perform their own translation of + the argument list (into a new ArgList data structure). Although + this allows the clang driver to match gcc easily, it also makes + the driver operation much harder to understand (since the Tools + 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 Tool + argument translation is done after the arguments have been + translated.

    + +

    A long term goal is to remove this tool chain specific + translation, and instead force each tool to change its own logic + to do the right thing on the untranslated original arguments.

    + +

    Unused Argument Warnings

    +

    The driver operates by parsing all arguments but giving Tools + the opportunity to choose which arguments to pass on. One + downside of this infrastructure is that if the user misspells + some option, or is confused about which options to use, some + command line arguments the user really cared about may go + unused. This problem is particularly important when using + clang as a compiler, since the clang compiler does not support + anywhere near all the options that gcc does, and we want to make + sure users know which ones are being used.

    + +

    To support this, the driver maintains a bit associated with + each argument of whether it has been used (at all) during the + compilation. This bit usually doesn't need to be set by hand, + as the key ArgList accessors will set it automatically.

    + +

    When a compilation is successful (there are no errors), the + driver checks the bit and emits an "unused argument" warning for + any arguments which were never accessed. This is conservative + (the argument may not have been used to do what the user wanted) + but still catches the most obvious cases.

    + + +

    Relation to GCC Driver Concepts

    + + +

    For those familiar with the gcc driver, this section provides + a brief overview of how things from the gcc driver map to the + clang driver.

    + +
      +
    • + Driver Driver +

      The driver driver is fully integrated into the clang + driver. The driver simply constructs additional Actions to + bind the architecture during the Pipeline + phase. The tool chain specific argument translation is + responsible for handling -Xarch_.

      + +

      The one caveat is that this approach + requires -Xarch_ not be used to alter the + compilation itself (for example, one cannot + provide -S as an -Xarch_ argument). The + driver attempts to reject such invocations, and overall + there isn't a good reason to abuse -Xarch_ to + that end in practice.

      + +

      The upside is that the clang driver is more efficient and + does little extra work to support universal builds. It also + provides better error reporting and UI consistency.

      +
      • + +
    • + Specs +

      The clang driver has no direct correspondant for + "specs". The majority of the functionality that is + embedded in specs is in the Tool specific argument + translation routines. The parts of specs which control the + compilation pipeline are generally part of + the Pipeline stage.

      +
      • + +
    • + Toolchains +

      The gcc driver has no direct understanding of tool + chains. Each gcc binary roughly corresponds to the + information which is embedded inside a single + ToolChain.

      + +

      The clang driver is intended to be portable and support + complex compilation environments. All platform and tool + chain specific code should be protected behind either + abstract or well defined interfaces (such as whether the + platform supports use as a driver driver).

      +
      • +
    +
    + + diff --git a/docs/main/InternalsManual.html b/docs/main/InternalsManual.html new file mode 100644 index 0000000000..daec6b0194 --- /dev/null +++ b/docs/main/InternalsManual.html @@ -0,0 +1,1681 @@ + + +"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 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, a SourceLocation to +"put the caret", an English translation associated with it, and a severity (e.g. +WARNING or ERROR). They can also optionally include a number +of arguments to the dianostic (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 diagonstic 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.

    + + +

    The Diagnostic*Kinds.def files

    + + +

    Diagnostics are created by adding an entry to one of the +clang/Basic/Diagnostic*Kinds.def files, depending on what library will +be using it. This file encodes the unique ID of the +diagnostic (as an enum, the first argument), the severity of the diagnostic +(second argument) and the English translation + format string.

    + +

    There is little sanity with the naming of the unique ID's right now. Some +start with err_, warn_, ext_ to encode the severity into the name. Since the +enum is referenced in the C++ code that produces the diagnostic, it is somewhat +useful for it to be reasonably short.

    + +

    The severity of the diagnostic comes from the set {NOTE, +WARNING, EXTENSION, EXTWARN, ERROR}. The +ERROR severity is used for diagnostics indicating the program is never +acceptable under any circumstances. When an error is emitted, the AST for the +input code may not be fully built. The EXTENSION and EXTWARN +severities are used for extensions to the language that Clang accepts. This +means that Clang fully understands and can represent them in the AST, but we +produce diagnostics to tell the user their code is non-portable. The difference +is that the former are ignored by default, and the later warn by default. The +WARNING severity is used for constructs that are valid in the currently +selected source language but that are dubious in some way. The NOTE +level is used to staple more information onto previous diagnostics.

    + +

    These severities are mapped into a smaller set (the +Diagnostic::Level enum, {Ignored, Note, Warning, +Error, Fatal }) of output levels by the diagnostics +subsystem based on various configuration options. Clang internally supports a +fully fine grained mapping mechanism that allows you to map almost any +diagnostic to the output level that you want. The only diagnostics that cannot +be mapped are NOTEs, which always follow the severity of the previously +emitted diagnostic and ERRORs, which can only be mapped to +Fatal (it is not possible to turn an error into a warning, +for example).

    + +

    Diagnostic mappings are used in many ways. For example, if the user +specifies -pedantic, EXTENSION maps to Warning, if +they specify -pedantic-errors, it turns into Error. This is +used to implement options like -Wunused_macros, -Wundef etc. +

    + +

    +Mapping to Fatal should only be used for diagnostics that are +considered so severe that error recovery won't be able to recover sensibly from +them (thus spewing a ton of bogus errors). One example of this class of error +are failure to #include a file. +

    + + +

    The Format String

    + + +

    The format string for the diagnostic is very simple, but it has some power. +It takes the form of a string in English with markers that indicate where and +how arguments to the diagnostic are inserted and formatted. For example, here +are some simple format strings:

    + +
    +  "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)"
+
    + +

    These examples show some important points of format strings. You can use any + plain ASCII character in the diagnostic string except "%" without a problem, + but these are C strings, so you have to use and be aware of all the C escape + sequences (as in the second example). If you want to produce a "%" in the + output, use the "%%" escape sequence, like the third diagnostic. Finally, + Clang uses the "%...[digit]" sequences to specify where and how arguments to + the diagnostic are formatted.

    + +

    Arguments to the diagnostic are numbered according to how they are specified + by the C++ code that produces them, and are + referenced by %0 .. %9. If you have more than 10 arguments + to your diagnostic, you are doing something wrong :). Unlike printf, there + is no requirement that arguments to the diagnostic end up in the output in + the same order as they are specified, you could have a format string with + "%1 %0" that swaps them, for example. The text in between the + percent and digit are formatting instructions. If there are no instructions, + the argument is just turned into a string and substituted in.

    + +

    Here are some "best practices" for writing the English format string:

    + +
      +
    • Keep the string short. It should ideally fit in the 80 column limit of the + DiagnosticKinds.def file. This avoids the diagnostic wrapping when + printed, and forces you to think about the important point you are conveying + with the diagnostic.
      • +
    • Take advantage of location information. The user will be able to see the + line and location of the caret, so you don't need to tell them that the + problem is with the 4th argument to the function: just point to it.
      • +
    • Do not capitalize the diagnostic string, and do not end it with a + period.
      • +
    • If you need to quote something in the diagnostic string, use single + quotes.
      • +
    + +

    Diagnostics should never take random English strings as arguments: you +shouldn't use "you have a problem with %0" and pass in things like +"your argument" or "your return value" as arguments. Doing +this prevents translating the Clang diagnostics to +other languages (because they'll get random English words in their otherwise +localized diagnostic). The exceptions to this are C/C++ language keywords +(e.g. auto, const, mutable, etc) and C/C++ operators (/=). Note +that things like "pointer" and "reference" are not keywords. On the other +hand, you can include anything that comes from the user's source code, +including variable names, types, labels, etc. The 'select' format can be +used to achieve this sort of thing in a localizable way, see below.

    + + +

    Formatting a Diagnostic Argument

    + + +

    Arguments to diagnostics are fully typed internally, and come from a couple +different classes: integers, types, names, and random strings. Depending on +the class of the argument, it can be optionally formatted in different ways. +This gives the DiagnosticClient information about what the argument means +without requiring it to use a specific presentation (consider this MVC for +Clang :).

    + +

    Here are the different diagnostic argument formats currently supported by +Clang:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    "s" format
    Example:"requires %1 parameter%s1"
    Class:Integers
    Description:This is a simple formatter for integers that is + useful when producing English diagnostics. When the integer is 1, it prints + as nothing. When the integer is not 1, it prints as "s". This allows some + simple grammatical forms to be to be handled correctly, and eliminates the + need to use gross things like "requires %1 parameter(s)".
    "select" format
    Example:"must be a %select{unary|binary|unary or binary}2 + operator"
    Class:Integers
    Description:

    This format specifier is used to merge multiple + related diagnostics together into one common one, without requiring the + difference to be specified as an English string argument. Instead of + specifying the string, the diagnostic gets an integer argument and the + format string selects the numbered option. In this case, the "%2" value + must be an integer in the range [0..2]. If it is 0, it prints 'unary', if + it is 1 it prints 'binary' if it is 2, it prints 'unary or binary'. This + allows other language translations to substitute reasonable words (or entire + phrases) based on the semantics of the diagnostic instead of having to do + things textually.

    +

    The selected string does undergo formatting.

    "plural" format
    Example:"you have %1 %plural{1:mouse|:mice}1 connected to + your computer"
    Class:Integers
    Description:

    This is a formatter for complex plural forms. + It is designed to handle even the requirements of languages with very + complex plural forms, as many Baltic languages have. The argument consists + of a series of expression/form pairs, separated by ':', where the first form + whose expression evaluates to true is the result of the modifier.

    +

    An expression can be empty, in which case it is always true. See the + example at the top. Otherwise, it is a series of one or more numeric + conditions, separated by ','. If any condition matches, the expression + matches. Each numeric condition can take one of three forms.

    +
      +
    • number: A simple decimal number matches if the argument is the same + as the number. Example: "%plural{1:mouse|:mice}4"
      • +
    • range: A range in square brackets matches if the argument is within + the range. Then range is inclusive on both ends. Example: + "%plural{0:none|1:one|[2,5]:some|:many}2"
      • +
    • modulo: A modulo operator is followed by a number, and + equals sign and either a number or a range. The tests are the + same as for plain + numbers and ranges, but the argument is taken modulo the number first. + Example: "%plural{%100=0:even hundred|%100=[1,50]:lower half|:everything + else}1"
      • +
    +

    The parser is very unforgiving. A syntax error, even whitespace, will + abort, as will a failure to match the argument against any + expression.

    "ordinal" format
    Example:"ambiguity in %ordinal0 argument"
    Class:Integers
    Description:

    This is a formatter which represents the + argument number as an ordinal: the value 1 becomes 1st, + 3 becomes 3rd, and so on. Values less than 1 + are not supported.

    +

    This formatter is currently hard-coded to use English ordinals.

    "objcclass" format
    Example:"method %objcclass0 not found"
    Class:DeclarationName
    Description:

    This is a simple formatter that indicates the + DeclarationName corresponds to an Objective-C class method selector. As + such, it prints the selector with a leading '+'.

    "objcinstance" format
    Example:"method %objcinstance0 not found"
    Class:DeclarationName
    Description:

    This is a simple formatter that indicates the + DeclarationName corresponds to an Objective-C instance method selector. As + such, it prints the selector with a leading '-'.

    "q" format
    Example:"candidate found by name lookup is %q0"
    Class:NamedDecl*
    Description

    This formatter indicates that the fully-qualified name of the declaration should be printed, e.g., "std::vector" rather than "vector".

    + +

    It is really easy to add format specifiers to the Clang diagnostics system, +but they should be discussed before they are added. If you are creating a lot +of repetitive diagnostics and/or have an idea for a useful formatter, please +bring it up on the cfe-dev mailing list.

    + + +

    Producing the Diagnostic

    + + +

    Now that you've created the diagnostic in the DiagnosticKinds.def file, you +need to write the code that detects the condition in question and emits the +new diagnostic. Various components of Clang (e.g. the preprocessor, Sema, +etc) provide a helper function named "Diag". It creates a diagnostic and +accepts the arguments, ranges, and other information that goes along with +it.

    + +

    For example, the binary expression error comes from code like this:

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

    This shows that use of the Diag method: they take a location (a SourceLocation object) and a diagnostic enum value +(which matches the name from DiagnosticKinds.def). If the diagnostic takes +arguments, they are specified with the << operator: the first argument +becomes %0, the second becomes %1, etc. The diagnostic interface allows you to +specify arguments of many different types, including int and +unsigned for integer arguments, const char* and +std::string for string arguments, DeclarationName and +const IdentifierInfo* for names, QualType for types, etc. +SourceRanges are also specified with the << operator, but do not have a +specific ordering requirement.

    + +

    As you can see, adding and producing a diagnostic is pretty straightforward. +The hard part is deciding exactly what you need to say to help the user, picking +a suitable wording, and providing the information needed to format it correctly. +The good news is that the call site that issues a diagnostic should be +completely independent of how the diagnostic is formatted and in what language +it is rendered. +

    + + +

    Code Modification Hints

    + + +

    In some cases, the front end emits diagnostics when it is clear +that some small change to the source code would fix the problem. For +example, a missing semicolon at the end of a statement or a use of +deprecated syntax that is easily rewritten into a more modern form. +Clang tries very hard to emit the diagnostic and recover gracefully +in these and other cases.

    + +

    However, for these cases where the fix is obvious, the diagnostic +can be annotated with a code +modification "hint" that describes how to change the code referenced +by the diagnostic to fix the problem. For example, it might add the +missing semicolon at the end of the statement or rewrite the use of a +deprecated construct into something more palatable. Here is one such +example C++ front end, where we warn about the right-shift operator +changing meaning from C++98 to C++0x:

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

    Here, the code modification hint is suggesting that parentheses be +added, and showing exactly where those parentheses would be inserted +into the source code. The code modification hints themselves describe +what changes to make to the source code in an abstract manner, which +the text diagnostic printer renders as a line of "insertions" below +the caret line. Other diagnostic +clients might choose to render the code differently (e.g., as +markup inline) or even give the user the ability to automatically fix +the problem.

    + +

    All code modification hints are described by the +CodeModificationHint class, instances of which should be +attached to the diagnostic using the << operator in the same way +that highlighted source ranges and arguments are passed to the +diagnostic. Code modification hints can be created with one of three +constructors:

    + +
    +
    CodeModificationHint::CreateInsertion(Loc, Code)
    +
    Specifies that the given Code (a string) should be inserted + before the source location Loc.
    + +
    CodeModificationHint::CreateRemoval(Range)
    +
    Specifies that the code in the given source Range + should be removed.
    + +
    CodeModificationHint::CreateReplacement(Range, Code)
    +
    Specifies that the code in the given source Range + should be removed, and replaced with the given Code string.
    +
    + + +

    The DiagnosticClient Interface

    + + +

    Once code generates a diagnostic with all of the arguments and the rest of +the relevant information, Clang needs to know what to do with it. As previously +mentioned, the diagnostic machinery goes through some filtering to map a +severity onto a diagnostic level, then (assuming the diagnostic is not mapped to +"Ignore") it invokes an object that implements the DiagnosticClient +interface with the information.

    + +

    It is possible to implement this interface in many different ways. For +example, the normal Clang DiagnosticClient (named 'TextDiagnosticPrinter') turns +the arguments into strings (according to the various formatting rules), prints +out the file/line/column information and the string, then prints out the line of +code, the source ranges, and the caret. However, this behavior isn't required. +

    + +

    Another implementation of the DiagnosticClient interface is the +'TextDiagnosticBuffer' class, which is used when Clang is in -verify mode. +Instead of formatting and printing out the diagnostics, this implementation just +captures and remembers the diagnostics as they fly by. Then -verify compares +the list of produced diagnostics to the list of expected ones. If they disagree, +it prints out its own output. +

    + +

    There are many other possible implementations of this interface, and this is +why we prefer diagnostics to pass down rich structured information in arguments. +For example, an HTML output might want declaration names be linkified to where +they come from in the source. Another example is that a GUI might let you click +on typedefs to expand them. This application would want to pass significantly +more information about types through to the GUI than a simple flat string. The +interface allows this to happen.

    + + +

    Adding Translations to Clang

    + + +

    Not possible yet! Diagnostic strings should be written in UTF-8, the client +can translate to the relevant code page if needed. Each translation completely +replaces the format string for the diagnostic.

    + + + +

    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 spelling location +and it's instantiation 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).

    + +

    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.

    + + +

    The Driver Library

    + + +

    The clang Driver and library are documented here.

    + + +

    Precompiled Headers

    + + +

    Clang supports two implementations of precompiled headers. The + default implementation, precompiled headers (PCH) uses a serialized representation + of Clang's internal data structures, encoded with the LLVM bitstream + format. Pretokenized headers (PTH), on the other hand, contain a + serialized representation of the tokens encountered when + preprocessing a header (and anything that header includes).

    + + + +

    The Frontend Library

    + + +

    The Frontend library contains functionality useful for building +tools on top of the clang libraries, for example several methods for +outputting diagnostics.

    + + +

    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 TokenLexer 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 matter. 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. +
      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. +
      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. +
      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 through an Actions module, it is passed around and Sema +intepretes it, based on the type of annotation token.
      • + +
    • 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 a pointer returned by Action::getTypeName(). In the case of the +Sema actions module, this is a Decl* for the type.
      2. + +
    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 returned +by the Action::ActOnCXXGlobalScopeSpecifier and +Action::ActOnCXXNestedNameSpecifier callbacks. In the case of Sema, this is a +DeclContext*.
      3. + +
    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.
      4. + +
    + +

    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 EOM 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 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. 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 typdefs. 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.

    + + +

    Canonical Types

    + + +

    Every instance of the Type class contains a canonical type pointer. For +simple types with no typedefs involved (e.g. "int", "int*", +"int**"), the type just points to itself. For types that have a +typedef somewhere in their structure (e.g. "foo", "foo*", +"foo**", "bar"), the canonical type pointer points to their +structurally equivalent type without any typedefs (e.g. "int", +"int*", "int**", and "int*" respectively).

    + +

    This design provides a constant time operation (dereferencing the canonical +type pointer) that gives us access to the structure of types. For example, +we can trivially tell that "bar" and "foo*" are the same type by dereferencing +their canonical type pointers and doing a pointer comparison (they both point +to the single "int*" type).

    + +

    Canonical types and typedef types bring up some complexities that must be +carefully managed. Specifically, the "isa/cast/dyncast" operators generally +shouldn't be used in code that is inspecting the AST. For example, when type +checking the indirection operator (unary '*' on a pointer), the type checker +must verify that the operand has a pointer type. It would not be correct to +check that with "isa<PointerType>(SubExpr->getType())", +because this predicate would fail if the subexpression had a typedef type.

    + +

    The solution to this problem are a set of helper methods on Type, used to +check their properties. In this case, it would be correct to use +"SubExpr->getType()->isPointerType()" to do the check. This +predicate will return true if the canonical type is a pointer, which is +true any time the type is structurally a pointer type. The only hard part here +is remembering not to use the isa/cast/dyncast operations.

    + +

    The second problem we face is how to get access to the pointer type once we +know it exists. To continue the example, the result type of the indirection +operator is the pointee type of the subexpression. In order to determine the +type, we need to get the instance of PointerType that best captures the typedef +information in the program. If the type of the expression is literally a +PointerType, we can return that, otherwise we have to dig through the +typedefs to find the pointer type. For example, if the subexpression had type +"foo*", we could return that type as the result. If the subexpression +had type "bar", we want to return "foo*" (note that we do +not want "int*"). In order to provide all of this, Type has +a getAsPointerType() method that checks whether the type is structurally a +PointerType and, if so, returns the best one. If not, it returns a null +pointer.

    + +

    This structure is somewhat mystical, but after meditating on it, it will +make sense to you :).

    + + +

    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.

    + + +

    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 8 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. Note that C++ overloaded operators (e.g., + "operator+") are represented as special kinds of + identifiers. Use IdentifierInfo's getOverloadedOperatorID + function to determine whether an identifier is an overloaded + operator name.
    + +
    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).
    +
    + +

    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.

    + +

    Redeclarations and Overloads

    +

    Within a translation unit, it is common for an entity to be +declared several times. For example, we might declare a function "f" + and then later re-declare it as part of an inlined definition:

    + +
    +void f(int x, int y, int z = 1);
+
+inline void f(int x, int y, int z) { /* ... */ }
+
    + +

    The representation of "f" differs in the source-centric and + semantics-centric views of a declaration context. In the + source-centric view, all redeclarations will be present, in the + order they occurred in the source code, making + this view suitable for clients that wish to see the structure of + the source code. In the semantics-centric view, only the most recent "f" + will be found by the lookup, since it effectively replaces the first + declaration of "f".

    + +

    In the semantics-centric view, overloading of functions is + represented explicitly. For example, given two declarations of a + function "g" that are overloaded, e.g.,

    +
    +void g();
+void g(int);
+
    +

    the DeclContext::lookup operation will return + an OverloadedFunctionDecl that contains both + declarations of "g". Clients that perform semantic analysis on a + program that is not concerned with the actual source code will + primarily use this semantics-centric view.

    + +

    Lexical and Semantic Contexts

    +

    Each declaration has two potentially different + declaration contexts: a lexical context, which corresponds to + the source-centric view of the declaration context, and + a semantic context, which corresponds to the + semantics-centric view. The lexical context is accessible + via Decl::getLexicalDeclContext while the + semantic context is accessible + via Decl::getDeclContext, both of which return + DeclContext pointers. For most declarations, the two + contexts are identical. For example:

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

    Here, the semantic and lexical contexts of X::f are + the DeclContext associated with the + class X (itself stored as a RecordDecl AST + node). However, we can now define X::f out-of-line:

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

    This definition of has different lexical and semantic + contexts. The lexical context corresponds to the declaration + context in which the actual declaration occurred in the source + code, e.g., the translation unit containing X. Thus, + this declaration of X::f can be found by traversing + the declarations provided by + [decls_begin(), decls_end()) in the + translation unit.

    + +

    The semantic context of X::f corresponds to the + class X, since this member function is (semantically) a + member of X. Lookup of the name f into + the DeclContext associated with X will + then return the definition of X::f (including + information about the default argument).

    + +

    Transparent Declaration Contexts

    +

    In C and C++, there are several contexts in which names that are + logically declared inside another declaration will actually "leak" + out into the enclosing scope from the perspective of name + lookup. The most obvious instance of this behavior is in + enumeration types, e.g.,

    +
    +enum Color {
+  Red, 
+  Green,
+  Blue
+};
+
    + +

    Here, Color is an enumeration, which is a declaration + context that contains the + enumerators Red, Green, + and Blue. Thus, traversing the list of declarations + contained in the enumeration Color will + yield Red, Green, + and Blue. However, outside of the scope + of Color one can name the enumerator Red + without qualifying the name, e.g.,

    + +
    +Color c = Red;
+
    + +

    There are other entities in C++ that provide similar behavior. For + example, linkage specifications that use curly braces:

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

    For source-level accuracy, we treat the linkage specification and + enumeration type as a + declaration context in which its enclosed declarations ("Red", + "Green", and "Blue"; "f" and "g") + are declared. However, these declarations are visible outside of the + scope of the declaration context.

    + +

    These language features (and several others, described below) have + roughly the same set of + requirements: declarations are declared within a particular lexical + context, but the declarations are also found via name lookup in + scopes enclosing the declaration itself. This feature is implemented + via transparent declaration contexts + (see DeclContext::isTransparentContext()), whose + declarations are visible in the nearest enclosing non-transparent + declaration context. This means that the lexical context of the + declaration (e.g., an enumerator) will be the + transparent DeclContext itself, as will the semantic + context, but the declaration will be visible in every outer context + up to and including the first non-transparent declaration context (since + transparent declaration contexts can be nested).

    + +

    The transparent DeclContexts are:

    +
      +
    • Enumerations (but not C++0x "scoped enumerations"): + 
      +enum Color { 
+  Red, 
+  Green, 
+  Blue 
+};
+// Red, Green, and Blue are in scope
+
      • +
    • C++ linkage specifications: + 
      +extern "C" {
+  void f(int);
+  void g(int);
+}
+// f and g are in scope
+
      • +
    • Anonymous unions and structs: + 
      +struct LookupTable {
+  bool IsVector;
+  union {
+    std::vector<Item> *Vector;
+    std::set<Item> *Set;
+  };
+};
+
+LookupTable LT;
+LT.Vector = 0; // Okay: finds Vector inside the unnamed union
+
      +
      • +
    • C++0x inline namespaces: +
      +namespace mylib {
+  inline namespace debug {
+    class X;
+  }
+}
+mylib::X *xp; // okay: mylib::X refers to mylib::debug::X
+
      +
      • +
    + + +

    Multiply-Defined Declaration Contexts

    +

    C++ namespaces have the interesting--and, so far, unique--property that +the namespace can be defined multiple times, and the declarations +provided by each namespace definition are effectively merged (from +the semantic point of view). For example, the following two code +snippets are semantically indistinguishable:

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

    In Clang's representation, the source-centric view of declaration + contexts will actually have two separate NamespaceDecl + nodes in Snippet #1, each of which is a declaration context that + contains a single declaration of "f". However, the semantics-centric + view provided by name lookup into the namespace N for + "f" will return an OverloadedFunctionDecl that contains + both declarations of "f".

    + +

    DeclContext manages multiply-defined declaration + contexts internally. The + function DeclContext::getPrimaryContext retrieves the + "primary" context for a given DeclContext instance, + which is the DeclContext responsible for maintaining + the lookup table used for the semantics-centric view. Given the + primary context, one can follow the chain + of DeclContext nodes that define additional + declarations via DeclContext::getNextContext. Note that + these functions are used internally within the lookup and insertion + methods of the DeclContext, so the vast majority of + clients can ignore them.

    + + +

    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.

    + + +

    Basic Blocks

    + + +

    Concretely, an instance of CFG is a collection of basic +blocks. Each basic block is an instance of CFGBlock, which +simply contains an ordered sequence of Stmt* (each referring +to statements in the AST). The ordering of statements within a block +indicates unconditional flow of control from one statement to the +next. Conditional control-flow +is represented using edges between basic blocks. The statements +within a given CFGBlock can be traversed using +the CFGBlock::*iterator interface.

    + +

    +A CFG object owns the instances of CFGBlock within +the control-flow graph it represents. Each CFGBlock within a +CFG is also uniquely numbered (accessible +via CFGBlock::getBlockID()). Currently the number is +based on the ordering the blocks were created, but no assumptions +should be made on how CFGBlocks are numbered other than their +numbers are unique and that they are numbered from 0..N-1 (where N is +the number of basic blocks in the CFG).

    + + +

    Entry and Exit Blocks

    + + +Each instance of CFG contains two special blocks: +an entry block (accessible via CFG::getEntry()), which +has no incoming edges, and an exit block (accessible +via CFG::getExit()), which has no outgoing edges. Neither +block contains any statements, and they serve the role of providing a +clear entrance and exit for a body of code such as a function body. +The presence of these empty blocks greatly simplifies the +implementation of many analyses built on top of CFGs. + + +

    Conditional Control-Flow

    + + +

    Conditional control-flow (such as those induced by if-statements +and loops) is represented as edges between CFGBlocks. +Because different C language constructs can induce control-flow, +each CFGBlock also records an extra Stmt* that +represents the terminator of the block. A terminator is simply +the statement that caused the control-flow, and is used to identify +the nature of the conditional control-flow between blocks. For +example, in the case of an if-statement, the terminator refers to +the IfStmt object in the AST that represented the given +branch.

    + +

    To illustrate, consider the following code example:

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

    After invoking the parser+semantic analyzer on this code fragment, +the AST of the body of foo is referenced by a +single Stmt*. We can then construct an instance +of CFG representing the control-flow graph of this function +body by single call to a static class method:

    + + +  Stmt* FooBody = ...
    +  CFG* FooCFG = CFG::buildCFG(FooBody); +     + +

    It is the responsibility of the caller of CFG::buildCFG +to delete the returned CFG* when the CFG is no +longer needed.

    + +

    Along with providing an interface to iterate over +its CFGBlocks, the CFG class also provides methods +that are useful for debugging and visualizing CFGs. For example, the +method +CFG::dump() dumps a pretty-printed version of the CFG to +standard error. This is especially useful when one is using a +debugger such as gdb. For example, here is the output +of FooCFG->dump():

    + + + [ 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): +     + +

    For each block, the pretty-printed output displays for each block +the number of predecessor blocks (blocks that have outgoing +control-flow to the given block) and successor blocks (blocks +that have control-flow that have incoming control-flow from the given +block). We can also clearly see the special entry and exit blocks at +the beginning and end of the pretty-printed output. For the entry +block (block B5), the number of predecessor blocks is 0, while for the +exit block (block B0) the number of successor blocks is 0.

    + +

    The most interesting block here is B4, whose outgoing control-flow +represents the branching caused by the sole if-statement +in foo. Of particular interest is the second statement in +the block, (x > 2), and the terminator, printed +as if [B4.2]. The second statement represents the +evaluation of the condition of the if-statement, which occurs before +the actual branching of control-flow. Within the CFGBlock +for B4, the Stmt* for the second statement refers to the +actual expression in the AST for (x > 2). Thus +pointers to subclasses of Expr can appear in the list of +statements in a block, and not just subclasses of Stmt that +refer to proper C statements.

    + +

    The terminator of block B4 is a pointer to the IfStmt +object in the AST. The pretty-printer outputs if +[B4.2] because the condition expression of the if-statement +has an actual place in the basic block, and thus the terminator is +essentially +referring to the expression that is the second statement of +block B4 (i.e., B4.2). In this manner, conditions for control-flow +(which also includes conditions for loops and switch statements) are +hoisted into the actual basic block.

    + + + + + + + + + +

    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 +unfortuate 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.

    + + +

    Implementation Approach

    + + +

    After trying several different approaches, we've finally converged on a +design (Note, at the time of this writing, not all of this has been implemented, +consider this a design goal!). Our basic approach is to define a single +recursive method evaluation method (Expr::Evaluate), which is +implemented in AST/ExprConstant.cpp. Given an expression with 'scalar' +type (integer, fp, complex, or pointer) this method returns the following +information:

    + +
      +
    • Whether the expression is an integer constant expression, a general + constant that was folded but has no side effects, a general constant that + was folded but that does have side effects, or an uncomputable/unfoldable + value. +
      • +
    • If the expression was computable in any way, this method returns the APValue + for the result of the expression.
      • +
    • If the expression is not evaluatable at all, this method returns + information on one of the problems with the expression. This includes a + SourceLocation for where the problem is, and a diagnostic ID that explains + the problem. The diagnostic should be have ERROR type.
      • +
    • If the expression is not an integer constant expression, this method returns + information on one of the problems with the expression. This includes a + SourceLocation for where the problem is, and a diagnostic ID that explains + the problem. The diagnostic should be have EXTENSION type.
      • +
    + +

    This information gives various clients the flexibility that they want, and we +will eventually have some helper methods for various extensions. For example, +Sema should have a Sema::VerifyIntegerConstantExpression method, which +calls Evaluate on the expression. If the expression is not foldable, the error +is emitted, and it would return true. If the expression is not an i-c-e, the +EXTENSION diagnostic is emitted. Finally it would return false to indicate that +the AST is ok.

    + +

    Other clients can use the information in other ways, for example, codegen can +just use expressions that are foldable in any way.

    + + +

    Extensions

    + + +

    This section describes how some of the various extensions Clang supports +interacts with constant evaluation:

    + +
      +
    • __extension__: The expression form of this extension causes + any evaluatable subexpression to be accepted as an integer constant + expression.
      • +
    • __builtin_constant_p: This returns true (as a integer + constant expression) if the operand is any evaluatable constant. As a + special case, if __builtin_constant_p is the (potentially + parenthesized) condition of a conditional operator expression ("?:"), only + the true side of the conditional operator is considered, and it is evaluated + with full constant folding.
      • +
    • __builtin_choose_expr: The condition is required to be an + integer constant expression, but we accept any constant as an "extension of + an extension". This only evaluates one operand depending on which way the + condition evaluates.
      • +
    • __builtin_classify_type: This always returns an integer + constant expression.
      • +
    • __builtin_inf,nan,..: These are treated just like a + floating-point literal.
      • +
    • __builtin_abs,copysign,..: These are constant folded as + general constant expressions.
      • +
    + + + + +
    + + diff --git a/docs/main/LanguageExtensions.html b/docs/main/LanguageExtensions.html new file mode 100644 index 0000000000..838b65f27b --- /dev/null +++ b/docs/main/LanguageExtensions.html @@ -0,0 +1,658 @@ + + +Clang Language Extensions + + + + + + + + +
    + +

    Clang Language Extensions

    + + + + +

    Introduction

    + + +

    This document describes the language extensions provided by Clang. In +addition to the language extensions listed here, Clang aims to support a broad +range of GCC extensions. Please see the GCC manual for +more information on these extensions.

    + + +

    Feature Checking Macros

    + + +

    Language extensions can be very useful, but only if you know you can depend +on them. In order to allow fine-grain features checks, we support two builtin +function-like macros. This allows you to directly test for a feature in your +code without having to resort to something like autoconf or fragile "compiler +version checks".

    + + +

    __has_builtin

    + + +

    This function-like macro takes a single identifier argument that is the name +of a builtin function. It evaluates to 1 if the builtin is supported or 0 if +not. It can be used like this:

    + +
    +
    +#ifndef __has_builtin         // Optional of course.
+  #define __has_builtin(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_builtin(__builtin_trap)
+  __builtin_trap();
+#else
+  abort();
+#endif
+...
+
    +
    + + + +

    __has_feature

    + + +

    This function-like macro takes a single identifier argument that is the name +of a feature. It evaluates to 1 if the feature is supported or 0 if not. It +can be used like this:

    + +
    +
    +#ifndef __has_feature         // Optional of course.
+  #define __has_feature(x) 0  // Compatibility with non-clang compilers.
+#endif
+
+...
+#if __has_feature(attribute_overloadable) || \
+    __has_feature(blocks)
+...
+#endif
+...
+
    +
    + +

    The feature tag is described along with the language feature below.

    + + +

    Include File Checking Macros

    + + +

    Not all developments systems have the same include files. +The __has_include and +__has_include_next macros allow you to +check for the existence of an include file before doing +a possibly failing #include directive.

    + + +

    __has_include

    + + +

    This function-like macro takes a single file name string argument that +is the name of an include file. It evaluates to 1 if the file can +be found using the include paths, or 0 otherwise:

    + +
    +
    +// Note the two possible file name string formats.
+#if __has_include("myinclude.h") && __has_include(<stdint.h>)
+# include "myinclude.h"
+#endif
+
+// To avoid problem with non-clang compilers not having this macro.
+#if defined(__has_include) && __has_include("myinclude.h")
+# include "myinclude.h"
+#endif
+
    +
    + +

    To test for this feature, use #if defined(__has_include).

    + + +

    __has_include_next

    + + +

    This function-like macro takes a single file name string argument that +is the name of an include file. It is like __has_include except that it +looks for the second instance of the given file found in the include +paths. It evaluates to 1 if the second instance of the file can +be found using the include paths, or 0 otherwise:

    + +
    +
    +// Note the two possible file name string formats.
+#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
+# include_next "myinclude.h"
+#endif
+
+// To avoid problem with non-clang compilers not having this macro.
+#if defined(__has_include_next) && __has_include_next("myinclude.h")
+# include_next "myinclude.h"
+#endif
+
    +
    + +

    Note that __has_include_next, like the GNU extension +#include_next directive, is intended for use in headers only, +and will issue a warning if used in the top-level compilation +file. A warning will also be issued if an absolute path +is used in the file argument.

    + + +

    Builtin Macros

    + + +
    +
    __BASE_FILE__
    +
    Defined to a string that contains the name of the main input + file passed to Clang.
    + +
    __COUNTER__
    +
    Defined to an integer value that starts at zero and is + incremented each time the __COUNTER__ macro is + expanded.
    + +
    __INCLUDE_LEVEL__
    +
    Defined to an integral value that is the include depth of the + file currently being translated. For the main file, this value is + zero.
    + +
    __TIMESTAMP__
    +
    Defined to the date and time of the last modification of the + current source file.
    + +
    __clang__
    +
    Defined when compiling with Clang
    + +
    __clang_major__
    +
    Defined to the major version number of Clang (e.g., the 2 in + 2.0.1).
    + +
    __clang_minor__
    +
    Defined to the minor version number of Clang (e.g., the 0 in + 2.0.1).
    + +
    __clang_patchlevel__
    +
    Defined to the patch level of Clang (e.g., the 1 in 2.0.1).
    + +
    __clang_version__
    +
    Defined to a string that captures the Clang version, including + the Subversion tag or revision number, e.g., "1.5 (trunk + 102332)".
    +
    + + +

    Vectors and Extended Vectors

    + + +

    Supports the GCC vector extensions, plus some stuff like V[1].

    + +

    Also supports ext_vector, which additionally support for V.xyzw +syntax and other tidbits as seen in OpenCL. An example is:

    + +
    +
    +typedef float float4 __attribute__((ext_vector_type(4)));
+typedef float float2 __attribute__((ext_vector_type(2)));
+
+float4 foo(float2 a, float2 b) {
+  float4 c;
+  c.xz = a;
+  c.yw = b;
+  return c;
+}
+
    + +

    Query for this feature with __has_feature(attribute_ext_vector_type).

    + +

    See also __builtin_shufflevector.

    + + +

    Checks for Standard Language Features

    + + +

    The __has_feature macro can be used to query if certain standard language features are +enabled. Those features are listed here.

    + +

    C++ exceptions

    + +

    Use __has_feature(cxx_exceptions) to determine if C++ exceptions have been enabled. For +example, compiling code with -fexceptions enables C++ exceptions.

    + +

    C++ RTTI

    + +

    Use __has_feature(cxx_rtti) to determine if C++ RTTI has been enabled. For example, +compiling code with -fno-rtti disables the use of RTTI.

    + + +

    Checks for Upcoming Standard Language Features

    + + +

    The __has_feature macro can be used to query if certain upcoming +standard language features are enabled. Those features are listed here.

    + +

    Currently, all features listed here are slated for inclusion in the upcoming +C++0x standard. As a result, all the features that clang supports are enabled +with the -std=c++0x option when compiling C++ code. Features that are +not yet implemented will be noted.

    + +

    C++0x decltype()

    + +

    Use __has_feature(cxx_decltype) to determine if support for the +decltype() specifier is enabled.

    + +

    C++0x attributes

    + +

    Use __has_feature(cxx_attributes) to determine if support for +attribute parsing with C++0x's square bracket notation is enabled. + +

    C++0x deleted functions

    + +

    Use __has_feature(cxx_deleted_functions) to determine if support for +deleted function definitions (with = delete) is enabled. + +

    C++ TR concepts

    + +

    Use __has_feature(cxx_concepts) to determine if support for +concepts is enabled. clang does not currently implement this feature. + +

    C++0x lambdas

    + +

    Use __has_feature(cxx_lambdas) to determine if support for +lambdas is enabled. clang does not currently implement this feature. + +

    C++0x nullptr

    + +

    Use __has_feature(cxx_nullptr) to determine if support for +nullptr is enabled. clang does not yet fully implement this feature. + +

    C++0x rvalue references

    + +

    Use __has_feature(cxx_rvalue_references) to determine if support for +rvalue references is enabled. clang does not yet fully implement this feature. + +

    C++0x static_assert()

    + +

    Use __has_feature(cxx_static_assert) to determine if support for +compile-time assertions using static_assert is enabled.

    + +

    C++0x type inference

    + +

    Use __has_feature(cxx_auto_type) to determine C++0x type inference +is supported using the auto specifier. If this is disabled, +auto will instead be a storage class specifier, as in C or C++98.

    + +

    C++0x variadic templates

    + +

    Use __has_feature(cxx_variadic_templates) to determine if support +for templates taking any number of arguments with the ellipsis notation is +enabled. clang does not yet fully implement this feature.

    + + +

    Blocks

    + + +

    The syntax and high level language feature description is in BlockLanguageSpec.txt. Implementation and ABI +details for the clang implementation are in Block-ABI-Apple.txt.

    + + +

    Query for this feature with __has_feature(blocks).

    + + +

    Function Overloading in C

    + + +

    Clang provides support for C++ function overloading in C. Function +overloading in C is introduced using the overloadable attribute. For +example, one might provide several overloaded versions of a tgsin +function that invokes the appropriate standard function computing the sine of a +value with float, double, or long double +precision:

    + +
    +
    +#include <math.h>
+float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
    +
    + +

    Given these declarations, one can call tgsin with a +float value to receive a float result, with a +double to receive a double result, etc. Function +overloading in C follows the rules of C++ function overloading to pick +the best overload given the call arguments, with a few C-specific +semantics:

    +
      +
    • Conversion from float or double to long + double is ranked as a floating-point promotion (per C99) rather + than as a floating-point conversion (as in C++).
      • + +
    • A conversion from a pointer of type T* to a pointer of type + U* is considered a pointer conversion (with conversion + rank) if T and U are compatible types.
      • + +
    • A conversion from type T to a value of type U + is permitted if T and U are compatible types. This + conversion is given "conversion" rank.
      • +
    + +

    The declaration of overloadable functions is restricted to +function declarations and definitions. Most importantly, if any +function with a given name is given the overloadable +attribute, then all function declarations and definitions with that +name (and in that scope) must have the overloadable +attribute. This rule even applies to redeclarations of functions whose original +declaration had the overloadable attribute, e.g.,

    + +
    +
    +int f(int) __attribute__((overloadable));
+float f(float); // error: declaration of "f" must have the "overloadable" attribute
+
+int g(int) __attribute__((overloadable));
+int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
    +
    + +

    Functions marked overloadable must have +prototypes. Therefore, the following code is ill-formed:

    + +
    +
    +int h() __attribute__((overloadable)); // error: h does not have a prototype
+
    +
    + +

    However, overloadable functions are allowed to use a +ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the unavailable attribute:

    + +
    +
    +void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
    +
    + +

    Functions declared with the overloadable attribute have +their names mangled according to the same rules as C++ function +names. For example, the three tgsin functions in our +motivating example get the mangled names _Z5tgsinf, +_Z5tgsind, and Z5tgsine, respectively. There are two +caveats to this use of name mangling:

    + +
      + +
    • Future versions of Clang may change the name mangling of + functions overloaded in C, so you should not depend on an specific + mangling. To be completely safe, we strongly urge the use of + static inline with overloadable functions.
      • + +
    • The overloadable attribute has almost no meaning when + used in C++, because names will already be mangled and functions are + already overloadable. However, when an overloadable + function occurs within an extern "C" linkage specification, + it's name will be mangled in the same way as it would in + C.
      • +
    + +

    Query for this feature with __has_feature(attribute_overloadable).

    + + + +

    Builtin Functions

    + + +

    Clang supports a number of builtin library functions with the same syntax as +GCC, including things like __builtin_nan, +__builtin_constant_p, __builtin_choose_expr, +__builtin_types_compatible_p, __sync_fetch_and_add, etc. In +addition to the GCC builtins, Clang supports a number of builtins that GCC does +not, which are listed here.

    + +

    Please note that Clang does not and will not support all of the GCC builtins +for vector operations. Instead of using builtins, you should use the functions +defined in target-specific header files like <xmmintrin.h>, which +define portable wrappers for these. Many of the Clang versions of these +functions are implemented directly in terms of extended +vector support instead of builtins, in order to reduce the number of +builtins that we need to implement.

    + + +

    __builtin_shufflevector

    + + +

    __builtin_shufflevector is used to express generic vector +permutation/shuffle/swizzle operations. This builtin is also very important for +the implementation of various target-specific header files like +<xmmintrin.h>. +

    + +

    Syntax:

    + +
    +__builtin_shufflevector(vec1, vec2, index1, index2, ...)
+
    + +

    Examples:

    + +
    +  // Identity operation - return 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
+
+  // "Splat" element 0 of V1 into a 4-element result.
+  __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
+
+  // Reverse 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
+
+  // Concatenate every other element of 4-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
+
+  // Concatenate every other element of 8-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
+
    + +

    Description:

    + +

    The first two arguments to __builtin_shufflevector are vectors that have the +same element type. The remaining arguments are a list of integers that specify +the elements indices of the first two vectors that should be extracted and +returned in a new vector. These element indices are numbered sequentially +starting with the first vector, continuing into the second vector. Thus, if +vec1 is a 4-element vector, index 5 would refer to the second element of vec2. +

    + +

    The result of __builtin_shufflevector is a vector +with the same element type as vec1/vec2 but that has an element count equal to +the number of indices specified. +

    + +

    Query for this feature with __has_builtin(__builtin_shufflevector).

    + + +

    __builtin_unreachable

    + + +

    __builtin_unreachable is used to indicate that a specific point in +the program cannot be reached, even if the compiler might otherwise think it +can. This is useful to improve optimization and eliminates certain warnings. +For example, without the __builtin_unreachable in the example below, +the compiler assumes that the inline asm can fall through and prints a "function +declared 'noreturn' should not return" warning. +

    + +

    Syntax:

    + +
    +__builtin_unreachable()
+
    + +

    Example of Use:

    + +
    +void myabort(void) __attribute__((noreturn));
+void myabort(void) {
+    asm("int3");
+    __builtin_unreachable();
+}
+
    + +

    Description:

    + +

    The __builtin_unreachable() builtin has completely undefined behavior. Since +it has undefined behavior, it is a statement that it is never reached and the +optimizer can take advantage of this to produce better code. This builtin takes +no arguments and produces a void result. +

    + +

    Query for this feature with __has_builtin(__builtin_unreachable).

    + + + +

    Target-Specific Extensions

    + + +

    Clang supports some language features conditionally on some targets.

    + + +

    X86/X86-64 Language Extensions

    + + +

    The X86 backend has these language extensions:

    + + +

    Memory references off the GS segment

    + + +

    Annotating a pointer with address space #256 causes it to be code generated +relative to the X86 GS segment register, and address space #257 causes it to be +relative to the X86 FS segment. Note that this is a very very low-level +feature that should only be used if you know what you're doing (for example in +an OS kernel).

    + +

    Here is an example:

    + +
    +#define GS_RELATIVE __attribute__((address_space(256)))
+int foo(int GS_RELATIVE *P) {
+  return *P;
+}
+
    + +

    Which compiles to (on X86-32):

    + +
    +_foo:
+	movl	4(%esp), %eax
+	movl	%gs:(%eax), %eax
+	ret
+
    + + +

    Static Analysis-Specific Extensions

    + + +

    Clang supports additional attributes that are useful for documenting program +invariants and rules for static analysis tools. The extensions documented here +are used by the path-sensitive static analyzer +engine that is part of Clang's Analysis library.

    + + +

    Analyzer Attributes

    + + +

    analyzer_noreturn

    + +

    Clang's static analysis engine understands the standard noreturn +attribute. This attribute, which is typically affixed to a function prototype, +indicates that a call to a given function never returns. Function prototypes for +common functions like exit are typically annotated with this attribute, +as well as a variety of common assertion handlers. Users can educate the static +analyzer about their own custom assertion handles (thus cutting down on false +positives due to false paths) by marking their own "panic" functions +with this attribute.

    + +

    While useful, noreturn is not applicable in all cases. Sometimes +there are special functions that for all intents and purposes should be +considered panic functions (i.e., they are only called when an internal program +error occurs) but may actually return so that the program can fail gracefully. +The analyzer_noreturn attribute allows one to annotate such functions +as being interpreted as "no return" functions by the analyzer (thus +pruning bogus paths) but will not affect compilation (as in the case of +noreturn).

    + +

    Usage: The analyzer_noreturn attribute can be placed in the +same places where the noreturn attribute can be placed. It is commonly +placed at the end of function prototypes:

    + +
    +  void foo() __attribute__((analyzer_noreturn));
+
    + +

    Query for this feature with __has_feature(attribute_analyzer_noreturn).

    + + +
    + + diff --git a/docs/main/Makefile b/docs/main/Makefile new file mode 100644 index 0000000000..a3999641a0 --- /dev/null +++ b/docs/main/Makefile @@ -0,0 +1,18 @@ +##===- docs/main/Makefile ----------------------------------*- Makefile -*-===## +# +# The LLVM Compiler Infrastructure +# +# This file is distributed under the University of Illinois Open Source +# License. See LICENSE.TXT for details. +# +##===----------------------------------------------------------------------===## + +LEVEL = ../../../.. + +include $(LEVEL)/Makefile.common + +MAIN.Project = clang +MAIN.project = clang +MAIN.man.center = clang Tools Documentation + +include $(LLVM_SRC_ROOT)/docs/mk/main.mk diff --git a/docs/main/PCHInternals.html b/docs/main/PCHInternals.html new file mode 100644 index 0000000000..e21ec5e90d --- /dev/null +++ b/docs/main/PCHInternals.html @@ -0,0 +1,500 @@ + + + Precompiled Headers (PCH) + + + + + + + + + +
    + +

    Precompiled Headers

    + +

    This document describes the design and implementation of Clang's + precompiled headers (PCH). If you are interested in the end-user + view, please see the User's Manual.

    + +

    Table of Contents

    + + +

    Using Precompiled Headers with clang

    + +

    The Clang compiler frontend, clang -cc1, supports two command line +options for generating and using PCH files.

    + +

    To generate PCH files using clang -cc1, use the option +-emit-pch: + +

     $ clang -cc1 test.h -emit-pch -o test.h.pch
    + +

    This option is transparently used by clang when generating +PCH files. The resulting PCH file contains the serialized form of the +compiler's internal representation after it has completed parsing and +semantic analysis. The PCH file can then be used as a prefix header +with the -include-pch option:

    + +
    +  $ clang -cc1 -include-pch test.h.pch test.c -o test.s
+
    + +

    Design Philosophy

    + +

    Precompiled headers are meant to improve overall compile times for + projects, so the design of precompiled headers is entirely driven by + performance concerns. The use case for precompiled headers is + relatively simple: when there is a common set of headers that is + included in nearly every source file in the project, we + precompile that bundle of headers into a single precompiled + header (PCH file). Then, when compiling the source files in the + project, we load the PCH file first (as a prefix header), which acts + as a stand-in for that bundle of headers.

    + +

    A precompiled header implementation improves performance when:

    +
      +
    • Loading the PCH file is significantly faster than re-parsing the + bundle of headers stored within the PCH file. Thus, a precompiled + header design attempts to minimize the cost of reading the PCH + file. Ideally, this cost should not vary with the size of the + precompiled header file.
      • + +
    • The cost of generating the PCH file initially is not so large + that it counters the per-source-file performance improvement due to + eliminating the need to parse the bundled headers in the first + place. This is particularly important on multi-core systems, because + PCH file generation serializes the build when all compilations + require the PCH file to be up-to-date.
      • +
    + +

    Clang's precompiled headers are designed with a compact on-disk +representation, which minimizes both PCH creation time and the time +required to initially load the PCH file. The PCH file itself contains +a serialized representation of Clang's abstract syntax trees and +supporting data structures, stored using the same compressed bitstream +as LLVM's bitcode +file format.

    + +

    Clang's precompiled headers are loaded "lazily" from disk. When a +PCH file is initially loaded, Clang reads only a small amount of data +from the PCH file to establish where certain important data structures +are stored. The amount of data read in this initial load is +independent of the size of the PCH file, such that a larger PCH file +does not lead to longer PCH load times. The actual header data in the +PCH file--macros, functions, variables, types, etc.--is loaded only +when it is referenced from the user's code, at which point only that +entity (and those entities it depends on) are deserialized from the +PCH file. With this approach, the cost of using a precompiled header +for a translation unit is proportional to the amount of code actually +used from the header, rather than being proportional to the size of +the header itself.

    + +

    When given the -print-stats option, Clang produces +statistics describing how much of the precompiled header was actually +loaded from disk. For a simple "Hello, World!" program that includes +the Apple Cocoa.h header (which is built as a precompiled +header), this option illustrates how little of the actual precompiled +header is required:

    + +
    +*** PCH Statistics:
+  933 stat cache hits
+  4 stat cache misses
+  895/39981 source location entries read (2.238563%)
+  19/15315 types read (0.124061%)
+  20/82685 declarations read (0.024188%)
+  154/58070 identifiers read (0.265197%)
+  0/7260 selectors read (0.000000%)
+  0/30842 statements read (0.000000%)
+  4/8400 macros read (0.047619%)
+  1/4995 lexical declcontexts read (0.020020%)
+  0/4413 visible declcontexts read (0.000000%)
+  0/7230 method pool entries read (0.000000%)
+  0 method pool misses
+
    + +

    For this small program, only a tiny fraction of the source +locations, types, declarations, identifiers, and macros were actually +deserialized from the precompiled header. These statistics can be +useful to determine whether the precompiled header implementation can +be improved by making more of the implementation lazy.

    + +

    Precompiled Header Contents

    + +Precompiled header layout + +

    Clang's precompiled headers are organized into several different +blocks, each of which contains the serialized representation of a part +of Clang's internal representation. Each of the blocks corresponds to +either a block or a record within LLVM's bitstream +format. The contents of each of these logical blocks are described +below.

    + +

    For a given precompiled header, the llvm-bcanalyzer +utility can be used to examine the actual structure of the bitstream +for the precompiled header. This information can be used both to help +understand the structure of the precompiled header and to isolate +areas where precompiled headers can still be optimized, e.g., through +the introduction of abbreviations.

    + +

    Metadata Block

    + +

    The metadata block contains several records that provide +information about how the precompiled header was built. This metadata +is primarily used to validate the use of a precompiled header. For +example, a precompiled header built for a 32-bit x86 target cannot be used +when compiling for a 64-bit x86 target. The metadata block contains +information about:

    + +
    +
    Language options
    +
    Describes the particular language dialect used to compile the +PCH file, including major options (e.g., Objective-C support) and more +minor options (e.g., support for "//" comments). The contents of this +record correspond to the LangOptions class.
    + +
    Target architecture
    +
    The target triple that describes the architecture, platform, and +ABI for which the PCH file was generated, e.g., +i386-apple-darwin9.
    + +
    PCH version
    +
    The major and minor version numbers of the precompiled header +format. Changes in the minor version number should not affect backward +compatibility, while changes in the major version number imply that a +newer compiler cannot read an older precompiled header (and +vice-versa).
    + +
    Original file name
    +
    The full path of the header that was used to generate the +precompiled header.
    + +
    Predefines buffer
    +
    Although not explicitly stored as part of the metadata, the +predefines buffer is used in the validation of the precompiled header. +The predefines buffer itself contains code generated by the compiler +to initialize the preprocessor state according to the current target, +platform, and command-line options. For example, the predefines buffer +will contain "#define __STDC__ 1" when we are compiling C +without Microsoft extensions. The predefines buffer itself is stored +within the source manager block, but its +contents are verified along with the rest of the metadata.
    + +
    + +

    Source Manager Block

    + +

    The source manager block contains the serialized representation of +Clang's SourceManager class, +which handles the mapping from source locations (as represented in +Clang's abstract syntax tree) into actual column/line positions within +a source file or macro instantiation. The precompiled header's +representation of the source manager also includes information about +all of the headers that were (transitively) included when building the +precompiled header.

    + +

    The bulk of the source manager block is dedicated to information +about the various files, buffers, and macro instantiations into which +a source location can refer. Each of these is referenced by a numeric +"file ID", which is a unique number (allocated starting at 1) stored +in the source location. Clang serializes the information for each kind +of file ID, along with an index that maps file IDs to the position +within the PCH file where the information about that file ID is +stored. The data associated with a file ID is loaded only when +required by the front end, e.g., to emit a diagnostic that includes a +macro instantiation history inside the header itself.

    + +

    The source manager block also contains information about all of the +headers that were included when building the precompiled header. This +includes information about the controlling macro for the header (e.g., +when the preprocessor identified that the contents of the header +dependent on a macro like LLVM_CLANG_SOURCEMANAGER_H) +along with a cached version of the results of the stat() +system calls performed when building the precompiled header. The +latter is particularly useful in reducing system time when searching +for include files.

    + +

    Preprocessor Block

    + +

    The preprocessor block contains the serialized representation of +the preprocessor. Specifically, it contains all of the macros that +have been defined by the end of the header used to build the +precompiled header, along with the token sequences that comprise each +macro. The macro definitions are only read from the PCH file when the +name of the macro first occurs in the program. This lazy loading of +macro definitions is triggered by lookups into the identifier table.

    + +

    Types Block

    + +

    The types block contains the serialized representation of all of +the types referenced in the translation unit. Each Clang type node +(PointerType, FunctionProtoType, etc.) has a +corresponding record type in the PCH file. When types are deserialized +from the precompiled header, the data within the record is used to +reconstruct the appropriate type node using the AST context.

    + +

    Each type has a unique type ID, which is an integer that uniquely +identifies that type. Type ID 0 represents the NULL type, type IDs +less than NUM_PREDEF_TYPE_IDS represent predefined types +(void, float, etc.), while other +"user-defined" type IDs are assigned consecutively from +NUM_PREDEF_TYPE_IDS upward as the types are encountered. +The PCH file has an associated mapping from the user-defined types +block to the location within the types block where the serialized +representation of that type resides, enabling lazy deserialization of +types. When a type is referenced from within the PCH file, that +reference is encoded using the type ID shifted left by 3 bits. The +lower three bits are used to represent the const, +volatile, and restrict qualifiers, as in +Clang's QualType +class.

    + +

    Declarations Block

    + +

    The declarations block contains the serialized representation of +all of the declarations referenced in the translation unit. Each Clang +declaration node (VarDecl, FunctionDecl, +etc.) has a corresponding record type in the PCH file. When +declarations are deserialized from the precompiled header, the data +within the record is used to build and populate a new instance of the +corresponding Decl node. As with types, each declaration +node has a numeric ID that is used to refer to that declaration within +the PCH file. In addition, a lookup table provides a mapping from that +numeric ID to the offset within the precompiled header where that +declaration is described.

    + +

    Declarations in Clang's abstract syntax trees are stored +hierarchically. At the top of the hierarchy is the translation unit +(TranslationUnitDecl), which contains all of the +declarations in the translation unit. These declarations (such as +functions or struct types) may also contain other declarations inside +them, and so on. Within Clang, each declaration is stored within a declaration +context, as represented by the DeclContext class. +Declaration contexts provide the mechanism to perform name lookup +within a given declaration (e.g., find the member named x +in a structure) and iterate over the declarations stored within a +context (e.g., iterate over all of the fields of a structure for +structure layout).

    + +

    In Clang's precompiled header format, deserializing a declaration +that is a DeclContext is a separate operation from +deserializing all of the declarations stored within that declaration +context. Therefore, Clang will deserialize the translation unit +declaration without deserializing the declarations within that +translation unit. When required, the declarations stored within a +declaration context will be deserialized. There are two representations +of the declarations within a declaration context, which correspond to +the name-lookup and iteration behavior described above:

    + +
      +
    • When the front end performs name lookup to find a name + x within a given declaration context (for example, + during semantic analysis of the expression p->x, + where p's type is defined in the precompiled header), + Clang deserializes a hash table mapping from the names within that + declaration context to the declaration IDs that represent each + visible declaration with that name. The entire hash table is + deserialized at this point (into the llvm::DenseMap + stored within each DeclContext object), but the actual + declarations are not yet deserialized. In a second step, those + declarations with the name x will be deserialized and + will be used as the result of name lookup.
      • + +
    • When the front end performs iteration over all of the + declarations within a declaration context, all of those declarations + are immediately de-serialized. For large declaration contexts (e.g., + the translation unit), this operation is expensive; however, large + declaration contexts are not traversed in normal compilation, since + such a traversal is unnecessary. However, it is common for the code + generator and semantic analysis to traverse declaration contexts for + structs, classes, unions, and enumerations, although those contexts + contain relatively few declarations in the common case.
      • +
    + +

    Statements and Expressions

    + +

    Statements and expressions are stored in the precompiled header in +both the types and the declarations blocks, because every statement or +expression will be associated with either a type or declaration. The +actual statement and expression records are stored immediately +following the declaration or type that owns the statement or +expression. For example, the statement representing the body of a +function will be stored directly following the declaration of the +function.

    + +

    As with types and declarations, each statement and expression kind +in Clang's abstract syntax tree (ForStmt, +CallExpr, etc.) has a corresponding record type in the +precompiled header, which contains the serialized representation of +that statement or expression. Each substatement or subexpression +within an expression is stored as a separate record (which keeps most +records to a fixed size). Within the precompiled header, the +subexpressions of an expression are stored prior to the expression +that owns those expression, using a form of Reverse +Polish Notation. For example, an expression 3 - 4 + 5 +would be represented as follows:

    + + + + + + + + +
    IntegerLiteral(3)
    IntegerLiteral(4)
    BinaryOperator(-)
    IntegerLiteral(5)
    BinaryOperator(+)
    STOP
    + +

    When reading this representation, Clang evaluates each expression +record it encounters, builds the appropriate abstract synax tree node, +and then pushes that expression on to a stack. When a record contains N +subexpressions--BinaryOperator has two of them--those +expressions are popped from the top of the stack. The special STOP +code indicates that we have reached the end of a serialized expression +or statement; other expression or statement records may follow, but +they are part of a different expression.

    + +

    Identifier Table Block

    + +

    The identifier table block contains an on-disk hash table that maps +each identifier mentioned within the precompiled header to the +serialized representation of the identifier's information (e.g, the +IdentifierInfo structure). The serialized representation +contains:

    + +
      +
    • The actual identifier string.
      • +
    • Flags that describe whether this identifier is the name of a + built-in, a poisoned identifier, an extension token, or a + macro.
      • +
    • If the identifier names a macro, the offset of the macro + definition within the preprocessor + block.
      • +
    • If the identifier names one or more declarations visible from + translation unit scope, the declaration IDs of these + declarations.
      • +
    + +

    When a precompiled header is loaded, the precompiled header +mechanism introduces itself into the identifier table as an external +lookup source. Thus, when the user program refers to an identifier +that has not yet been seen, Clang will perform a lookup into the +identifier table. If an identifier is found, its contents (macro +definitions, flags, top-level declarations, etc.) will be deserialized, at which point the corresponding IdentifierInfo structure will have the same contents it would have after parsing the headers in the precompiled header.

    + +

    Within the PCH file, the identifiers used to name declarations are represented with an integral value. A separate table provides a mapping from this integral value (the identifier ID) to the location within the on-disk +hash table where that identifier is stored. This mapping is used when +deserializing the name of a declaration, the identifier of a token, or +any other construct in the PCH file that refers to a name.

    + +

    Method Pool Block

    + +

    The method pool block is represented as an on-disk hash table that +serves two purposes: it provides a mapping from the names of +Objective-C selectors to the set of Objective-C instance and class +methods that have that particular selector (which is required for +semantic analysis in Objective-C) and also stores all of the selectors +used by entities within the precompiled header. The design of the +method pool is similar to that of the identifier +table: the first time a particular selector is formed during the +compilation of the program, Clang will search in the on-disk hash +table of selectors; if found, Clang will read the Objective-C methods +associated with that selector into the appropriate front-end data +structure (Sema::InstanceMethodPool and +Sema::FactoryMethodPool for instance and class methods, +respectively).

    + +

    As with identifiers, selectors are represented by numeric values +within the PCH file. A separate index maps these numeric selector +values to the offset of the selector within the on-disk hash table, +and will be used when de-serializing an Objective-C method declaration +(or other Objective-C construct) that refers to the selector.

    + +

    Precompiled Header Integration Points

    + +

    The "lazy" deserialization behavior of precompiled headers requires +their integration into several completely different submodules of +Clang. For example, lazily deserializing the declarations during name +lookup requires that the name-lookup routines be able to query the +precompiled header to find entities within the PCH file.

    + +

    For each Clang data structure that requires direct interaction with +the precompiled header logic, there is an abstract class that provides +the interface between the two modules. The PCHReader +class, which handles the loading of a precompiled header, inherits +from all of these abstract classes to provide lazy deserialization of +Clang's data structures. PCHReader implements the +following abstract classes:

    + +
    +
    StatSysCallCache
    +
    This abstract interface is associated with the + FileManager class, and is used whenever the file + manager is going to perform a stat() system call.
    + +
    ExternalSLocEntrySource
    +
    This abstract interface is associated with the + SourceManager class, and is used whenever the + source manager needs to load the details + of a file, buffer, or macro instantiation.
    + +
    IdentifierInfoLookup
    +
    This abstract interface is associated with the + IdentifierTable class, and is used whenever the + program source refers to an identifier that has not yet been seen. + In this case, the precompiled header implementation searches for + this identifier within its identifier table + to load any top-level declarations or macros associated with that + identifier.
    + +
    ExternalASTSource
    +
    This abstract interface is associated with the + ASTContext class, and is used whenever the abstract + syntax tree nodes need to loaded from the precompiled header. It + provides the ability to de-serialize declarations and types + identified by their numeric values, read the bodies of functions + when required, and read the declarations stored within a + declaration context (either for iteration or for name lookup).
    + +
    ExternalSemaSource
    +
    This abstract interface is associated with the Sema + class, and is used whenever semantic analysis needs to read + information from the global method + pool.
    +
    + +
    + + + diff --git a/docs/main/PCHLayout.graffle b/docs/main/PCHLayout.graffle new file mode 100644 index 0000000000..5c96bfb701 --- /dev/null +++ b/docs/main/PCHLayout.graffle @@ -0,0 +1,1880 @@ + + + + + ActiveLayerIndex + 0 + ApplicationVersion + + com.omnigroup.OmniGrafflePro + 137.11.0.108132 + + AutoAdjust + + BackgroundGraphic + + Bounds + {{0, 0}, {576, 733}} + Class + SolidGraphic + ID + 2 + Style + + shadow + + Draws + NO + + stroke + + Draws + NO + + + + CanvasOrigin + {0, 0} + ColumnAlign + 1 + ColumnSpacing + 36 + CreationDate + 2009-06-02 11:19:43 -0700 + Creator + Douglas Gregor + DisplayScale + 1 0/72 in = 1.0000 in + GraphDocumentVersion + 6 + GraphicsList + + + Bounds + {{35, 301}, {104, 30}} + Class + ShapedGraphic + ID + 13 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 0.175793 + g + 0.402929 + r + 1 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Method Pool} + + + + Bounds + {{32, 58}, {110, 14}} + Class + ShapedGraphic + FitText + YES + Flow + Resize + ID + 12 + Layer + 0 + Shape + Rectangle + Style + + fill + + Draws + NO + + shadow + + Draws + NO + + stroke + + Draws + NO + + + Text + + Pad + 0 + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Precompiled Header} + VerticalPad + 0 + + Wrap + NO + + + Bounds + {{35, 190}, {104, 30}} + Class + ShapedGraphic + ID + 11 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 1 + g + 0.796208 + r + 0.324589 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Types} + + + + Bounds + {{35, 227}, {104, 30}} + Class + ShapedGraphic + ID + 10 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 1 + g + 0.382716 + r + 0.524072 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Declarations} + + + + Bounds + {{35, 264}, {104, 30}} + Class + ShapedGraphic + ID + 8 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 0.99938 + g + 0.457913 + r + 1 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Identifier Table} + + + + Bounds + {{35, 153}, {104, 30}} + Class + ShapedGraphic + ID + 7 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 0.669993 + g + 1 + r + 0.254644 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Preprocessor} + + + + Bounds + {{35, 116}, {104, 30}} + Class + ShapedGraphic + ID + 6 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 0.258332 + g + 1 + r + 0.593784 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Source Manager} + + + + Bounds + {{35, 79}, {104, 30}} + Class + ShapedGraphic + ID + 5 + Layer + 0 + Shape + Rectangle + Style + + fill + + Color + + b + 0.270873 + g + 1 + r + 0.979351 + + + stroke + + CornerRadius + 9 + + + Text + + Text + {\rtf1\ansi\ansicpg1252\cocoartf949\cocoasubrtf460 +{\fonttbl\f0\fswiss\fcharset0 Helvetica;} +{\colortbl;\red255\green255\blue255;} +\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural + +\f0\fs24 \cf0 Metadata} + + + + Bounds + {{21, 47}, {132, 293}} + Class + ShapedGraphic + ID + 4 + Layer + 1 + Shape + Rectangle + Style + + fill + + FillType + 2 + GradientAngle + 90 + + stroke + + CornerRadius + 9 + + + + + GridInfo + + GuidesLocked + NO + GuidesVisible + YES + HPages + 1 + ImageCounter + 1 + KeepToScale + + Layers + + + Lock + NO + Name + Sub-blocks + Print + YES + View + YES + + + Lock + NO + Name + PCH Block + Print + YES + View + YES + + + LayoutInfo + + Animate + NO + circoMinDist + 18 + circoSeparation + 0.0 + layoutEngine + dot + neatoSeparation + 0.0 + twopiSeparation + 0.0 + + LinksVisible + NO + MagnetsVisible + NO + MasterSheets + + ModificationDate + 2009-06-03 08:22:05 -0700 + Modifier + Douglas Gregor + NotesVisible + NO + Orientation + 2 + OriginVisible + NO + PageBreaks + YES + PrintInfo + + NSBottomMargin + + float + 41 + + NSLeftMargin + + float + 18 + + NSPaperSize + + size + {612, 792} + + NSRightMargin + + float + 18 + + NSTopMargin + + float + 18 + + + PrintOnePage + + QuickLookPreview + + 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 + u8g0NxaWNXOayzQULnMoLmef3nIRcOD2SYu2CS80BleQE5ZJLzzXU+NZRcPC+zTYM4r+ + fRwPl/pzSueMwj0xDQGJPzEKt5PVbvu43ox3+rdxeffaTVjuKHiDcAiYWdgO1xXkqtxR + vMtswI0iU7qklCLTHlw3FUBw9cAOjQ3BIHr5jC4FwM9n0mblMxo+F+TPcy1/FJHxtpC4 + pp2gyEfT2FgKoJkzaYOhYAPtLWwgfKEAvLGlAIhmBUCRLnuTvw1mAR9AcgH4VvPepRqT + Ei1+mKLLHKUACGYFQBH+tIWCS81Tb5HRZilJAXhsLAXQzGku01C4zKG4TPi2Nsv30pMC + 8B434R7t/oRreKW/393pz7vdZuqyX/4HnD2NIAplbmRzdHJlYW0KZW5kb2JqCjUgMCBv + YmoKMTkzOQplbmRvYmoKMiAwIG9iago8PCAvVHlwZSAvUGFnZSAvUGFyZW50IDMgMCBS + IC9SZXNvdXJjZXMgNiAwIFIgL0NvbnRlbnRzIDQgMCBSIC9NZWRpYUJveCBbMCAwIDU3 + NiA3MzNdCj4+CmVuZG9iago2IDAgb2JqCjw8IC9Qcm9jU2V0IFsgL1BERiAvVGV4dCAv + SW1hZ2VCIC9JbWFnZUMgL0ltYWdlSSBdIC9Db2xvclNwYWNlIDw8IC9DczIgMjUgMCBS + Ci9DczEgNyAwIFIgPj4gL0ZvbnQgPDwgL0YxLjAgMjYgMCBSID4+IC9YT2JqZWN0IDw8 + IC9JbTEgOCAwIFIgL0ltMiAxMSAwIFIKL0ltMyAxMyAwIFIgL0ltNSAxNyAwIFIgL0lt + NyAyMSAwIFIgL0ltOCAyMyAwIFIgL0ltNCAxNSAwIFIgL0ltNiAxOSAwIFIgPj4KL1No + YWRpbmcgPDwgL1NoMSAxMCAwIFIgPj4gPj4KZW5kb2JqCjEwIDAgb2JqCjw8IC9Db2xv + clNwYWNlIDcgMCBSIC9TaGFkaW5nVHlwZSAyIC9Db29yZHMgWyA2Ni41IC0xNDcgNjYu + NDk5OTUgMTQ3IF0gL0RvbWFpbgpbIDAgMSBdIC9FeHRlbmQgWyBmYWxzZSBmYWxzZSBd + IC9GdW5jdGlvbiAyNyAwIFIgPj4KZW5kb2JqCjggMCBvYmoKPDwgL0xlbmd0aCA5IDAg + UiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dpZHRoIDMwOCAvSGVpZ2h0 + IDYzMCAvQ29sb3JTcGFjZQoyOCAwIFIgL1NNYXNrIDI5IDAgUiAvQml0c1BlckNvbXBv + bmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae3QMQEAAADCoPVP + bQlPiEBhwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGPgMDOJgAAEK + ZW5kc3RyZWFtCmVuZG9iago5IDAgb2JqCjI1NjIKZW5kb2JqCjExIDAgb2JqCjw8IC9M + ZW5ndGggMTIgMCBSIC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGgg + MjUyIC9IZWlnaHQgMTA0IC9Db2xvclNwYWNlCjMxIDAgUiAvU01hc2sgMzIgMCBSIC9C + aXRzUGVyQ29tcG9uZW50IDggL0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB + 7dABDQAAAMKg909tDjeIQGHAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + +B4YMy8AAQplbmRzdHJlYW0KZW5kb2JqCjEyIDAgb2JqCjM2NgplbmRvYmoKMTMgMCBv + YmoKPDwgL0xlbmd0aCAxNCAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdl + IC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKMzEgMCBSIC9TTWFzayAz + NCAwIFIgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+Pgpz + dHJlYW0KeAHt0AENAAAAwqD3T20ON4hAYcCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBj4HhgzLwABCmVuZHN0cmVhbQplbmRvYmoKMTQgMCBvYmoKMzY2CmVuZG9i + agoxNyAwIG9iago8PCAvTGVuZ3RoIDE4IDAgUiAvVHlwZSAvWE9iamVjdCAvU3VidHlw + ZSAvSW1hZ2UgL1dpZHRoIDI1MiAvSGVpZ2h0IDEwNCAvQ29sb3JTcGFjZQozMSAwIFIg + L1NNYXNrIDM2IDAgUiAvQml0c1BlckNvbXBvbmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVj + b2RlID4+CnN0cmVhbQp4Ae3QAQ0AAADCoPdPbQ43iEBhwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGPgeGDMvAAEKZW5kc3RyZWFtCmVuZG9iagoxOCAwIG9iagoz + NjYKZW5kb2JqCjIxIDAgb2JqCjw8IC9MZW5ndGggMjIgMCBSIC9UeXBlIC9YT2JqZWN0 + IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggMjUyIC9IZWlnaHQgMTA0IC9Db2xvclNwYWNl + CjMxIDAgUiAvU01hc2sgMzggMCBSIC9CaXRzUGVyQ29tcG9uZW50IDggL0ZpbHRlciAv + RmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7dABDQAAAMKg909tDjeIQGHAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY+B4YMy8AAQplbmRzdHJlYW0KZW5kb2JqCjIy + IDAgb2JqCjM2NgplbmRvYmoKMjMgMCBvYmoKPDwgL0xlbmd0aCAyNCAwIFIgL1R5cGUg + L1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0Nv + bG9yU3BhY2UKMzEgMCBSIC9TTWFzayA0MCAwIFIgL0JpdHNQZXJDb21wb25lbnQgOCAv + RmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHt0AENAAAAwqD3T20ON4hAYcCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgw + YMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMG + DBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCA + AQMGDBgwYMCAAQMGDBgwYMCAAQMGDBgwYMCAAQMGDBj4HhgzLwABCmVuZHN0cmVhbQpl + bmRvYmoKMjQgMCBvYmoKMzY2CmVuZG9iagoxNSAwIG9iago8PCAvTGVuZ3RoIDE2IDAg + UiAvVHlwZSAvWE9iamVjdCAvU3VidHlwZSAvSW1hZ2UgL1dpZHRoIDI1MiAvSGVpZ2h0 + IDEwNCAvQ29sb3JTcGFjZQozMSAwIFIgL1NNYXNrIDQyIDAgUiAvQml0c1BlckNvbXBv + bmVudCA4IC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4Ae3QAQ0AAADCoPdP + bQ43iEBhwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBg + wIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYM + GDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIAB + AwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGDBgwIABAwYMGPgeGDMvAAEKZW5k + c3RyZWFtCmVuZG9iagoxNiAwIG9iagozNjYKZW5kb2JqCjE5IDAgb2JqCjw8IC9MZW5n + dGggMjAgMCBSIC9UeXBlIC9YT2JqZWN0IC9TdWJ0eXBlIC9JbWFnZSAvV2lkdGggMjUy + IC9IZWlnaHQgMTA0IC9Db2xvclNwYWNlCjMxIDAgUiAvU01hc2sgNDQgMCBSIC9CaXRz + UGVyQ29tcG9uZW50IDggL0ZpbHRlciAvRmxhdGVEZWNvZGUgPj4Kc3RyZWFtCngB7dAB + DQAAAMKg909tDjeIQGHAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDA + gAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY + MGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAED + BgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwYMGDAgAEDBgwY+B4Y + My8AAQplbmRzdHJlYW0KZW5kb2JqCjIwIDAgb2JqCjM2NgplbmRvYmoKMjkgMCBvYmoK + PDwgL0xlbmd0aCAzMCAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9X + aWR0aCAzMDggL0hlaWdodCA2MzAgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkgL0JpdHNQ + ZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHt2ulX + leUaBvAUZdrMbkCGTWwhBkEGBVFcECJhIGgZqEWyQNKUBFoYYgtDMhLRAmWJohE4oCSz + KKBm6/xr53424HABeXc6X3q7ng+nLr3Oxud3nuHdr+eddzgoQAEKUIACFPi/C6yy/Pi/ + kRmp1S+Hm0XHywmuNvP9O3gLWm5ua9asWfsvGDJNNzcX3//o5gITLmPl7uHhuTi8LDcW + Z+bp4eFuZjsP95fZ5sHM6nIXLS8vb5sMHxm+lhxmZmaG3l5enp4GThacrLe/xGZOMLPC + 3MVLuHx8/fz8/QMCAi08AgL8/f38fIXOW9wMm0tNe7SZRSZissK8bDbhEqugdXZ7cHBI + SEioJYdMLDjYbl8XFBgYIHA2m5dZbUZNudTmxdZ6eHrbfPz8DZdIhYWHh0dEREZGOiw4 + ZFoRETLBsNDQEAPn7+dj8/b0mF9rmlt0nsysMV+/gCB7cOj68AiH493oaKdzQ4xlxwan + Mzr6XYcjInx9aLA9KEAWm6y1+aX2tv1p9qVsSxHzMWIC5oiKdsbExsXFJyQmJm6cH0mW + GQsTkqklxMfFxcY4o6McwmbUfERNNujb9+cCmbfNJRYWGRUtXgkbk5NTUlPT0mVstuAw + 80pLTU1JTt6YIG7RUZFhLjXZoPNof7rSFsl8/ALtIWGR7zpj4xKFK31LxtasrG3bs1+N + HRYYr2aTvX1bVtbWjC3pApcYF+t8NzIsxB7o56NAc5F5eNp8/QPtoRFRztiEpJS0LZlZ + 2TtycvPydubvMqPAYsM1qfydeXm5OTuyszK3pKUkJcQ6oyJC7YH+vjZzqMn2XHGlCZmb + nGVCFhQc5oiOiU9KTc/ctiM3b9cHhR8WFe8pKSktLd1ruSGTKinZU1z0YeEHu/Jyd2zL + TE9Nio+JdoQFBxk097XmmWMltFULZAHrQsIdG+ISU9K3ZufsLNhdXLLvo/2flJcfOHjI + ouPggfLyT/Z/tK+keHfBzpzsrekpiXEbHOEh6wIW0FYyE7I17p7evv5CFhUTn5yWmZ2b + X1i89+Pyg59WVFZWVR05UmPGF5YarikdOVJVVVlZ8enB8o/3Fhfm52ZnpiXHx0QJmr+v + nGnydLsCmnnK8PDy8Q8yZAmbNmfl5Bfu2Vd2qKKyuubY8RO1J0/W1dXX1zdYbMiU6upO + nqw9cfxYTXVlxaGyfXsK83OyNm9KMGhB/j5eriNt2c1pdqac/36BwUKWmJKx/f2CIhE7 + XH30+Ff1Xzeeamo63XzGoqP5dFPTqcav6786frT6sKgVFby/PSMlUdCCA/3MPbDCQlsl + y8yQ2cMcMQkpGdl5hSX7RexYbX1jU/O3Ld+1nmtr+96io63tXOt3Ld82NzXW1x4Ttf0l + hXnZGSkJMY4weeSwecrdudzmdC0zL58Ae2ikM36TkO0uLfus6mhtw6nmlta28+0XOjou + dl6y6Oi82NFxof18W2tL86mG2qNVn5WV7ha0TfHOyFB7gNmdyy60hWUmh1l0XPLm7Xm7 + 95ZXHDle13impe2HC52Xfu7q7r5y9WqPJcfVq1e6u7t+vtR54Ye2ljONdcePVJTv3Z23 + fXNyXLQcaSsutNWr5QLwDbCHyWGWlvV+YWn55zUnGppazrV3XO660nOt9/qNPhk3LTjM + vG5c773Wc6Xrckf7uZamhhM1n5eXFr6flSZHWpg9wFcW2urVS24BszXlNAsyOzMlI6eg + pKyi5sTXzWfPd1zu7untu/lL/68DAwODg4O3LTdkUjK1X/t/udnX29N9ueP82eavT9RU + lJUU5GSkmN3pWmjLbE7Zmu7mNAuLik1Kz95ZtP+zaiFrbe/s6um92T9w+87de0ND92U8 + sNwwsxoaunf3zu2B/pu9PV2d7a2CVv3Z/qKd2elJsWah+Xi5L3MLrJKt6e0XGBLhjE/d + mlu471DVlw1Cdqn7Wl//4N2hB8O/PRxxjVHLjfl5Pfxt+MHQ3cH+vmvdlwSt4cuqQ/sK + c7emxjsjQgL9vGVzLrk5XVvT377eEbsxPTt/T9nho3VN3wlZ762BO/eHR0bHxscnJicn + pyw5ZGIT4+NjoyPD9+8M3OoVtO+a6o4eLtuTn52+Mdax3u4vjxtuSw4019aUx9nouE2Z + ObLMqmsbW853CtngveGRsYmpqUfTjy09ph9NTU2MjQzfGxS0zvMtjbXVstByMjfJ1Rkc + 6NqccAnIcWa2ZmjkhsS0bXnFZYePNTSf6+i6dmtwaHh0Ymr68ZOZ2fkxZ7mxMLGZJ4+n + pyZGh4cGb13r6jjX3HDscFlx3ra0xA2RoWZzLjnQzHFm81u3Pio2ecuOgr2yzE61tF/u + 6Ru499vY5PST2dm5p88sPp7Ozc4+mZ4c++3eQF/P5faWU7LQ9hbs2JIcG7V+nZ9t6YEm + Zp42f7tszZTMnN0fVxytb27r6L7ef2d4dHJ6ZlbAnv8u44VFh5nb82fPns7OTE+ODt/p + v97d0dZcf7Ti4905mSmyOV0HGl4Cq+TpzCcwOMKZkJqVV1RWebyx5YfLPTcHh0Ympmfm + BGwR6w8LjsW5CdvczPTEyNDgzZ7LP7Q0Hq8sK8rLSk1wRsiBJpcAXJyr3dy9fOU4i0lM + z95VcrD6q6bWC129/XeHx6Yezz57Lp8KVv+xwIApySSfP5t9PDU2fLe/t+tCa9NX1QdL + dmWnJ8bIgebr5Y4Xp5h5y5cAR2ySHGf7Pq2pa267eKVvYOjh+PTMUyCzgNZrU3gNzqA9 + nZkefzg00HflYltzXc2n++RAS4p1yFcB76Vm5tqUK+C95Iycwo8qjjV8e/5Sz83bD0Ym + ZZnJxnztk/947Qda4F9fn9mLF7/LQpsceXD7Zs+l8982HKv4qDAnI/k9cwmYi/PNhw15 + 1LD52cPk6Wxr7of7D3/Z2NL+07Vf7sjWfDInZosfbAGjZaewOD8xm3sim/POL9d+am9p + /PLw/g9zt8oTWphdLs6lZvPXZry5Aj6pPHHq7I8/m+Ns/NHMnGzNhc9c9udZ4hcXJiib + c27m0bg50H7+8eypE5WfmEsgfv7iXGImjxoB8qhhrs3isqrab1o7uq7/eu+hmMlxZnmy + //xnEU0OtEfjD+/9er2ro/Wb2ip5qpWLU8wC5NsT7k1jFhzulG8BO/eUV8m12dF9Q66A + ienZl2aWWFArTmIeTS6B2ekJuQRudHfIxVlVvmenfBNwhgevaBYh35y255ccqD55+txF + YyZPZ+YKcH3eij/NIr/hmqS5BMwTmphdPHf6ZPWBkvzt8u0pYgUzH3kRtMH1eHbgyMnm + tk7zqLFwbZqPs4jMn0zDzHLh4jQPG51tzSePHHA9oG2Q10HyULt0b4rZ4iOteTwTs8H7 + r8z+5GdZ5rdemd0fdJnV1Sw+1P6Zmbw821V6qKbuzPeXrv67za5e+v5MXc2hUvkisDEm + UmFWTzNjVk+ztx0ib+xNmr2Ny/X7/18z1Y+0QGnx3pQ74K3rzLxydN2bC3cAnmcW4FBN + 4S1mb7xAo9k8Kc1US+uN0l8yk1fb8prWEbNxs+v5zOxNeX12f9S8pZWvTm98sIWDfBEw + b2pH75sXaIvPGps3xjjkRS2+3Ja/DjCvth0xSZvN3zp90TBv9kDM5sTMwkowNTGbEzPX + S8fvzzR8Yf7maXOSy8wL/kKAZgt2NINFpIg0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYA + oog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB + hWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0 + UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBBhWYAoog0UyBB5a+Z + efoGhjpiNm7O3lV6qKb+zPeXem4O3h+dejz77MUff8AnWzb+IWazj6dG7w/e7Ln0/Zn6 + mkOlu7I3b4xxhAb6eq51W/XOa2PV6rWePoEhkTEb01+aXe0bvD8yKWa/v/j3mL34Xcwm + R+4P9l19aZa+MSYyJNDHc+1qmi2zW/6g2TIqf/5Lf8XsHe5NF+ZbzF47zeRf32L277gF + /pAr4E/PM5ot2aY0W0Ly1l/4e2Z18nz2+rPGv3Rv1rmez149ayy/NxPl+azkYE1dc1vn + ldeez/6FZlc625rrag6W7MpOT1x8PlvOLGKDy+zAkZOnjdnA0OIzrazat67sf3xBJrl4 + BwwN9InZ6ZNHDrjMNkTMP9MuMbMFBItZ2vb8kgPVJ0+fu9h9Q8wmpl3fA8zH/eNN3jIB + M0eX2fTEyNDAje6L506frD5Qkr89LXFDRHCATb4HLGcW7kxM27ZzT3nVV02tHcbsoZg9 + fS5fOM14y8/8h//2/BxfPH86Oz3x0Jh1tDZ9VVW+Z+e2tERn+Ipm9vDohNSsvOKyqtpv + Wju6rv967+H4o5mXZpZGmyf7Q8xmHo0/vPfr9a6O1m9qq8qK87JSE6LD7cutszWeNn8x + ixezok8qT5w6++PPvf13h8Vs7vmLhYVmYbRFshfP58Rs+G5/788/nj11ovKTIjGLFzN/ + m+ca3JtrPGx+9rDouE1bcz/cf/jLxpb2n679cmd4bOrJnHmxsTD+4ftvxT/+4vzka8Dc + k6mx4Tu/XPupvaXxy8P7P8zduikuOszuZ/NYxszbb936qPeSM3IKP6o41vDteXmBdvvB + wsX5Es18+Io/+R/5G4tc5p8vFr46Pbgtr8/Of9twrOKjwpyM5Pei1q/z815q5ubu7RcU + 6ohN2rKjYN+n5gHtonnYeDg+bQ60l7vTfPI/kmbFP7SZ0cKQacpxNj0uV0DflYvm8ezT + fQU7tiTFOkKD/Lzd3XBvurl7yYvayJj5h9pquTgvdJkDbcy8qQU08yNW/DP8g35j0eo1 + MvOWdswcZ10X5NqsXnyklde0XkvMVrmZF7XBEU5zcRaVVR5vbPnhsrzdNk9oM3PPnv8u + /xu4BvwcS8TFuf3+/NncjHk6kzfbl39oaTxeWWaugARnRLB5Tfvmq+133jEvt10XZ1xK + Zs7ujyuO1je3dXRf778zPDo5PTP79JmwyVj8dKv908zt+bNnT2dnpidHh+/0X+/uaGuu + P1rx8e6czJS4+WsTXm27zOTilEsgNlkOtL2HqmtPtbRf7ukbuPfb2OT0k9nZOWGz9ng6 + Nzv7ZHpy7Ld7A309l9tbTtVWH9orx1lyrLkCbB7LmK3x8PaTA02+PW2Tp9rDxxqaz3V0 + Xbs1ODQ8OjE1/fjJzOz8mLPcWJjYzJPH01MTo8NDg7eudXWca244dlieaOVbwIbI0EDX + tfnGX6HI96jVa9y95EALlye0zJzCfbLQGlvOd3b33hq8NzwyNjE19Wj6saXH9KOpqYmx + keF7g7d6uzvPtzTKMttXmJMpT2fhcpx5uePjmZjJJSAH2npHrPx1Xf6essNH65rOtl8S + tIE794dHRsfGxycmJyenLDlkYhPj42OjI8P37wwI2aX2s011Rw+X7cnPTt8Y61hvvgWs + xUeN+QNNNmdIhDM+dWuuLLSqLxuaWwXtWl//4N2hB8O/PRxxjVHLjfl5Pfxt+MHQ3cH+ + vmtC1trc8GWVLLPcranxTnkRJFtzyXFmzMzmDLCHRcUmpWfvLNr/WfWJrwWts6un92b/ + wO07d+8NDd2X8cByw8xqaOje3Tu3B/pv9vZ0dQrZ1yeqP9tftDM7PSk2Kswe4NqaeJyJ + mdmc8lUg0hmfkpFTUFJWUSNoZ893XO7u6e27+Uv/rwMDA4ODg7ctN2RSMrVf+3+52dfb + 03254/xZIaupKCspyMlIiXdGypcA19ZcYvbO6tVrPbx8zUKLSUzLer+wtPzzmhMNTS3n + 2jsud13pudZ7/UafjJsWHGZeN673Xuu50nW5o/1cS1PDiZrPy0sL389KS4wxy8zXS7Ym + fHMy7x9lc7oWWohcncmbt+ft3lteceR4XeOZlrYfLnRe+rmru/vK1as9lhxXr17p7u76 + +VLnhR/aWs401h0/UlG+d3fe9s3JcmmGuJbZmjf/zxrzb2zN5vQwJ5rZnZsysvN2l5Z9 + VnW0tuFUc0tr2/n2Cx0dFzsvWXR0XuzouNB+vq21pflUQ+3Rqs/KSnfnZWdsMjvTnGYe + cmsu3ZovF1qgPcwRk5AiaIUl+w8drj5WW9/Y1Pxty3et59ravrfoaGs71/pdy7fNTY31 + tceqDx/aX1IoZCkJMY4we6A5zZZdZsZMFppcA/JgK0daSsb29wuK9pWJ2tHjX9V/3Xiq + qel08xmLjubTTU2nGr+u/+r4UREr21dU8P72jBQ5zORxVshWWmbyWCsnmuxO/6AQQUvY + tDkrJ79wj6hVVFbXHDt+ovbkybq6+vr6BosNmVJd3cmTtSeOH6uprqwQsT2F+TlZmzcl + CFlIkL/ZmWuWuwHmbwG3Ne6e3r7+6wxafHJaZnZufmHx3o/LD35aUVlZVXXkSI0ZX1hq + uKZ05EhVVWVlxacHyz/eW1yYn5udmZYcb8jW+ft6e7qvWf40W0Bb6+5p8w0QNMeGuMSU + 9K3ZOTsLdheX7Pto/yfl5QcOHrLoOHigvPyT/R/tKyneXbAzJ3trekpi3AaHkAX42jzd + V7gAXHfnqtVypBk0/6DgMEd0THxSanrmth25ebs+KPywqHhPSUlpaeleyw2ZVEnJnuKi + Dws/2JWXu2NbZnpqUnxMtCMsOMh/gWzZS3PxecMcaQYt0B4aEeWMTUhKSduSmZW9Iyc3 + L29n/i4zCiw2XJPK35mXl5uzIzsrc0taSlJCrDMqItQeaMhch9lyzxnzZObuFDQ503z8 + Au0hYZHvOmPjEpNTUtO3ZGzNytq2PfvV2GGB8Wo22du3ZWVtzdiSnpqSnBgX63w3MixE + HjJ85Cwz5/+fkb1Cs/kFBNlDwyKjomNi4xI2Jgtcalq6jM0WHGZeaanClbwxIS42Jjoq + MizUHhTgZ1ORvbNqYaV52XxcauvDHVHRTnGLi09ITEzcOD+SLDMWJiRTS4iPEy9ndJQj + fL1LzMfmtbDK/nyZyR41F4E51LxsvkYtOHR9eITD8W50tNO5IcayY4PTGR39rsMRIWDB + Zo35ipgcZW5v25gvLwJBEzVvWWv+gUHr7CGhoWHh4eEREZGRkQ4LDplWRIRMMCw0NMS+ + LijQ389HtqXHWjWZrLT5peZu1posNr+AQANnDw4OCRE9Kw6ZWHCw3XAFBvjJEjNrTA5/ + s8jeui9fuz7NBpUb1NPL22bzETh//wCxs+4ICPD3Fy4fm83by1POMZfYWy7MRa6F/SlL + TdQMm4e4GTihk+FryWFmZmbo7SVessLWrjFr7C8ssgU9s0NXu5nVZuBEbmF4WW4szszT + w3CZFfY/gb222lxwZsVZf6yR5WW4/ocV9sY2XSXD9TGu/3Cz6Hg1QzPfNwD+TjAfZu3x + d3T436UABShAAQpQYAWB/wIyjvCaCmVuZHN0cmVhbQplbmRvYmoKMzAgMCBvYmoKNzcy + OAplbmRvYmoKMzIgMCBvYmoKPDwgL0xlbmd0aCAzMyAwIFIgL1R5cGUgL1hPYmplY3Qg + L1N1YnR5cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UK + L0RldmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29k + ZSA+PgpzdHJlYW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aup + iXZwlDqYMuaIy+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+ + j4+PV94R8I6AdwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFd + Pz9sGP5PfgwcsBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOURO + g0ikwEA0AJAAEP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO + 5BBxEpkM2MAcEspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkI + G4jZERERHA6Xy+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8 + S3y+QBAlxL2iBAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJ + VCqNcSkWd3IbA4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6 + jGMhfwnx8XKZLEYC/PxILhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6Xj + SAeuVGmpSmVKUqICBkAaLRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2do + NJlZ2Ug5OBVmLitTo8lQp6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF + 4th4RXJqeoYm+1ft1bz8Ap2usLCwCLcCczpdQX7eVe2v2ZqM9NRkRXysWMjnsVkhCN7/ + AprrToI/50anh4ZF8KKipXJFikqdmZObryu+VnKjtLSsvALnKi8rLb1Rcq1Yl5+bk6lW + pSjk0ugoXkRYKN0NfxI7oJ/3DwwKpgF6pFAsS0hWZWRp84uul5bfrKyurqmpqzMg/Q+X + wqzV1dXUVFdX3iwvvV6Ur83KUCUnyMTCSICnBUPNwyrnBHg0uwWQKLQQhC6Ju6xUZ2kL + ivUVldW1hobGpuaWFqOxtbW1DacCa0ZjS0tzU2ODoba6skJfXKDNUisvx0kQfAiNQsJK + /tikRxkPfY7KYAG6VJ6UdiUnD8irausb77TeNbV3dHSa7+Fc5s6OjnbT3dY7jfW1VUCf + l3MlLUkuBXgWg4r63QmBPwdhR+hMNk8okSepNFpdCZA3NLeaOsz3LQ+6e6zWP3Auq7Wn + +4HlvrnD1NrcAPQlOq1GlSSXCHlsmOrIgdDrj0t6LOwkCp0ZzhWI4wA9t1B/q6a+ua3d + bOm29vb122wDg0M41+CAzdbf12vttpjb25rra27pC3MBPk4s4IYz6Sjrjw28O+xQ7Pxo + 2eU0TW5RaWVdo9F0z2J92D849GhkdHRsfNyOa42Pj42OjjwaGux/aLXcMxkb6ypLi3I1 + aZdl0Xwo+RMD7+sLjS6YzmRDsScor2gLS38zNLV1WHr6bMMjY/aJyanH06AZHAv5ezw1 + OWEfGxm29fVYOtqaDL+VFmqvKBOg5NlMejAE3tf3SLdDKQ/VHoIyXp6kztHpKw1Nd81d + vbbhUfvk9MzT2Wdzc3MOh+M5bgXmwOKz2acz05P20WFbb5f5bpOhUq/LUSfJUdZjgT8m + 6SHl/VG1syNFsQpVZl7JrVpA7+4bHLFPzszOPZ9fWFxaegF6iVshd0tLiwvzz+dmZybt + I4N93QBfe6skL1OliBWhwFNI/sd0u3OQ8kFURhhHII5PydAWV9TcbgP0odGJ6VnHwtLL + 5Vcrq5jWcCuXv5VXyy+XFhyz0xOjQwDfdrumolibkRIvFnDCGNQgSPojnR5LeRrzIk8U + o1BlFeir6o0dDwB98snc/Ivl1bX1jY3Nra2tbVwLDG5ubKyvrS6/mJ97MgnwDzqM9VX6 + giyVIkbEu8ikwTTnd6TgsZSHZQ0/Oi5ZDWGvbTZZegcB3bG4vLq+ub392vnmTMj5ent7 + c311edEB8IO9FlNzLQRenRwHrZ7FwJL+ULODckcpH86NkiakavL1VQ1t5h7byMQTx9Ly + 2ua2883O7p5L+7iV2+Duzhvn9uba8pLjycSIrcfc1lClz9ekJkijuOEo6Y8UPCp3MjX0 + YqRIlpieUwRhb7f0Ddun5xZfrW85d/b29t++OyN6u7+3t+PcWn+1ODdtH+6ztEPgi3LS + E2WiyIuhVPLRggf2QDKNCSkvT1bnXq+sbzVbbaNTs/PLa1vO3T0Af/836APOhTy+f/fu + 7d6uc2tteX52atRmNbfWV17PVSfLIemxgj/c7M7B7E5hsDgCSbxSk6evbjRZHg7bZxxL + q5vO3X0A90D/g2N5PAL+/q5zc3XJMWMffmgxNVbr8zTKeImAAwUPze5Qo/f18ycFQ7kL + pQpVtq689k5Hd//I5OzC8vr2m7137+Gqh5g/4kiHrIHZ9+/23myvLy/MTo70d3fcqS3X + ZasUUiEUfDDJ/3CjB/YgWNTxRLFQ7sU3DUazdWBsem5pZcO5+/YQOo6oP7Py2QAg+Le7 + zo2VpbnpsQGr2Wi4WQwFHyviwdIu6Cg7avPQ6n6RJam11yob2u73Dtlnnr9c3YKwQ8J/ + duV/PvtCHP3zc4cfPvwNgd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLun + ZFwtqbptsvT9NfF0HlJ+Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ + 6I+yu9q8GLW6G9VN7V1/PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+g + Zid2Nfoj7DDF0WGKQ20+X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+u + gdUNNHpgp8Oq9nDOI3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8 + aoNGX1NakAkrO0EE60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCn + s6W2TJeVBqtazgnsFLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbB + R8FtLCxujuY8sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j8 + 52AfH/rjntFQUQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf + +Srcffwj2c/S9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n8 + 6r0M3L8T9h6W2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI + /I6Zz3HvFnad/XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A + 6HaE3ROKAk/YvcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4 + ndAVeSKe7YNFHg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxG + tIfKhY8qn2BndSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2C + dwS8I+AdAe8I/BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKMzMgMCBvYmoKMjc2MApl + bmRvYmoKNDIgMCBvYmoKPDwgL0xlbmd0aCA0MyAwIFIgL1R5cGUgL1hPYmplY3QgL1N1 + YnR5cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0Rl + dmljZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+ + PgpzdHJlYW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZw + lDqYMuaIy+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+P + V94R8I6AdwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9s + GP5PfgwcsBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ik + wEA0AJAAEP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBx + EpkM2MAcEspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZ + ERERHA6Xy+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+ + QBAlxL2iBAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqN + cSkWd3IbA4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMh + 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 + NHpgp8Oq9nDOI3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNG + X1NakAkrO0EE60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2 + TJeVBqtazgnsFLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8Ft + LCxujuY8sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852Af + H/rjntFQUQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Src + ffwj2c/S9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M + 3L8T9h6W2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Z + z3HvFnad/XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE + 3ROKAk/YvcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAV + eSKe7YNFHg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfK + hY8qn2BndSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8 + I+AdAe8I/BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKNDMgMCBvYmoKMjc2MAplbmRv + YmoKNDQgMCBvYmoKPDwgL0xlbmd0aCA0NSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5 + cGUgL0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0Rldmlj + ZUdyYXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+Pgpz + dHJlYW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqY + MuaIy+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R + 8I6AdwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5P + fgwcsBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0 + AJAAEP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM + 2MAcEspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERER + HA6Xy+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAl + xL2iBAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkW + d3IbA4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMhfwnx + 8XKZLEYC/PxILhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6XjSAeuVGmp + SmVKUqICBkAaLRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2doNJlZ2Ug5 + OBVmLitTo8lQp6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF4th4RXJq + eoYm+1ft1bz8Ap2usLCwCLcCczpdQX7eVe2v2ZqM9NRkRXysWMjnsVkhCN7/AprrToI/ + 50anh4ZF8KKipXJFikqdmZObryu+VnKjtLSsvALnKi8rLb1Rcq1Yl5+bk6lWpSjk0ugo + XkRYKN0NfxI7oJ/3DwwKpgF6pFAsS0hWZWRp84uul5bfrKyurqmpqzMg/Q+XwqzV1dXU + VFdX3iwvvV6Ur83KUCUnyMTCSICnBUPNwyrnBHg0uwWQKLQQhC6Ju6xUZ2kLivUVldW1 + hobGpuaWFqOxtbW1DacCa0ZjS0tzU2ODoba6skJfXKDNUisvx0kQfAiNQsJK/tikRxkP + fY7KYAG6VJ6UdiUnD8irausb77TeNbV3dHSa7+Fc5s6OjnbT3dY7jfW1VUCfl3MlLUku + BXgWg4r63QmBPwdhR+hMNk8okSepNFpdCZA3NLeaOsz3LQ+6e6zWP3Auq7Wn+4HlvrnD + 1NrcAPQlOq1GlSSXCHlsmOrIgdDrj0t6LOwkCp0ZzhWI4wA9t1B/q6a+ua3dbOm29vb1 + 22wDg0M41+CAzdbf12vttpjb25rra27pC3MBPk4s4IYz6Sjrjw28O+xQ7Pxo2eU0TW5R + aWVdo9F0z2J92D849GhkdHRsfNyOa42Pj42OjjwaGux/aLXcMxkb6ypLi3I1aZdl0Xwo + +RMD7+sLjS6YzmRDsScor2gLS38zNLV1WHr6bMMjY/aJyanH06AZHAv5ezw1OWEfGxm2 + 9fVYOtqaDL+VFmqvKBOg5NlMejAE3tf3SLdDKQ/VHoIyXp6kztHpKw1Nd81dvbbhUfvk + 9MzT2Wdzc3MOh+M5bgXmwOKz2acz05P20WFbb5f5bpOhUq/LUSfJUdZjgT8m6SHl/VG1 + syNFsQpVZl7JrVpA7+4bHLFPzszOPZ9fWFxaegF6iVshd0tLiwvzz+dmZybtI4N93QBf + e6skL1OliBWhwFNI/sd0u3OQ8kFURhhHII5PydAWV9TcbgP0odGJ6VnHwtLL5Vcrq5jW + cCuXv5VXyy+XFhyz0xOjQwDfdrumolibkRIvFnDCGNQgSPojnR5LeRrzIk8Uo1BlFeir + 6o0dDwB98snc/Ivl1bX1jY3Nra2tbVwLDG5ubKyvrS6/mJ97MgnwDzqM9VX6giyVIkbE + u8ikwTTnd6TgsZSHZQ0/Oi5ZDWGvbTZZegcB3bG4vLq+ub392vnmTMj5ent7c311edEB + 8IO9FlNzLQRenRwHrZ7FwJL+ULODckcpH86NkiakavL1VQ1t5h7byMQTx9Ly2ua2883O + 7p5L+7iV2+Duzhvn9uba8pLjycSIrcfc1lClz9ekJkijuOEo6Y8UPCp3MjX0YqRIlpie + UwRhb7f0Ddun5xZfrW85d/b29t++OyN6u7+3t+PcWn+1ODdtH+6ztEPgi3LSE2WiyIuh + VPLRggf2QDKNCSkvT1bnXq+sbzVbbaNTs/PLa1vO3T0Af/836APOhTy+f/fu7d6uc2tt + eX52atRmNbfWV17PVSfLIemxgj/c7M7B7E5hsDgCSbxSk6evbjRZHg7bZxxLq5vO3X0A + 90D/g2N5PAL+/q5zc3XJMWMffmgxNVbr8zTKeImAAwUPze5Qo/f18ycFQ7kLpQpVtq68 + 9k5Hd//I5OzC8vr2m7137+Gqh5g/4kiHrIHZ9+/23myvLy/MTo70d3fcqS3XZasUUiEU + fDDJ/3CjB/YgWNTxRLFQ7sU3DUazdWBsem5pZcO5+/YQOo6oP7Py2QAg+Le7zo2Vpbnp + sQGr2Wi4WQwFHyviwdIu6Cg7avPQ6n6RJam11yob2u73Dtlnnr9c3YKwQ8J/duV/PvtC + HP3zc4cfPvwNgd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLunZFwtqbpt + svT9NfF0HlJ+Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ6I+yu9q8 + GLW6G9VN7V1/PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+gZid2Nfoj + 7DDF0WGKQ20+X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpg + p8Oq9nDOI3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1Na + kAkrO0EE60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeV + BqtazgnsFLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxu + juY8sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rj + ntFQUQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj + 2c/S9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T + 9h6W2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3Hv + Fnad/XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROK + Ak/YvcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe + 7YNFHg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8q + n2BndSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+Ad + Ae8I/BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKNDUgMCBvYmoKMjc2MAplbmRvYmoK + NDAgMCBvYmoKPDwgL0xlbmd0aCA0MSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUg + L0ltYWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdy + YXkgL0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJl + YW0KeAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaI + y+TCUdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6A + dwS8I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5Pfgwc + sBGzf0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAA + EP9vwkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAc + EspkslhhYWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERERHA6X + y+XhWGCPwwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAlxL2i + BAI+/xKPx4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkWd3Ib + A4sScXS0SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMhfwnx8XKZ + LEYC/PxILhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6XjSAeuVGmpSmVK + UqICBkAaLRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2doNJlZ2Ug5OBVm + LitTo8lQp6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF4th4RXJqeoYm + +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 + sHuWNmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQ + UQgLuxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S + 9I6ta93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W + 2M8uiPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad + /XcLu07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/Y + vcBY1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNF + Hg7yIuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2Bn + dSJ4Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I + /BQj8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKNDEgMCBvYmoKMjc2MAplbmRvYmoKMzQg + MCBvYmoKPDwgL0xlbmd0aCAzNSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0lt + YWdlIC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkg + L0JpdHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0K + eAHtnPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaIy+TC + UdMyyaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6AdwS8 + I+AdARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5PfgwcsBGz + f0BAoEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAAEP9v + wkcVjiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAcEspk + 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 + PvwNgd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLunZFwtqbptsvT9NfF0 + HlJ+Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ6I+yu9q8GLW6G9VN + 7V1/PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+gZid2Nfoj7DDF0WGK + Q20+X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpgp8Oq9nDO + I3ZWhABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1NakAkrO0EE + 60R2Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeVBqtazgns + FLiBjcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxujuY8sHuW + Nmh6B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQUQgL + uxgh9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S9I6t + a93z+4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W2M8u + iPrM6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad/XcL + u07zbiGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/YvcBY + 1qPt7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNFHg7y + IuKZTrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2BndSJ4 + Nz7En3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I/BQj + 8C9ppK71CmVuZHN0cmVhbQplbmRvYmoKMzUgMCBvYmoKMjc2MAplbmRvYmoKMzggMCBv + YmoKPDwgL0xlbmd0aCAzOSAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdl + IC9XaWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkgL0Jp + dHNQZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHt + nPlXUukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaIy+TCUdMy + yaXM3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6AdwS8I+Ad + ARiBc2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5PfgwcsBGzf0BA + oEck3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAAEP9vwkcV + jiLuD9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAcEspkslhh + YWHhuBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERERHA6Xy+XhWGCP + wwGj7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAlxL2iBAI+/xKP + x4m4GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkWd3IbA4sScXS0 + SCjgR/IAH9FTgB4S/+t570YPImPkbG4kH7glMTKZPD4+QQG6jGMhfwnx8XKZLEYC/PxI + Lhujh8R3wX8x8h50CpXBDGNzLwlE0VLAViQmpSiVqWmqA6XjSAeuVGmpSmVKUqICBkAa + LRJc4rLDmAwq5RTwGHpAIDmYxmCGcyIFIkmsPCExWalKV2doNJlZ2Ug5OBVmLitTo8lQ + p6uUyYkJ8liJSBDJCWcyaMFkVPSQ9idGHtD9oNYBPYTF5vGF4th4RXJqeoYm+1ft1bz8 + Ap2usLCwCLcCczpdQX7eVe2v2ZqM9NRkRXysWMjnsVkhCN7/AprrToI/50anh4ZF8KKi + pXJFikqdmZObryu+VnKjtLSsvALnKi8rLb1Rcq1Yl5+bk6lWpSjk0ugoXkRYKN0NfxI7 + oJ/3DwwKpgF6pFAsS0hWZWRp84uul5bfrKyurqmpqzMg/Q+XwqzV1dXUVFdX3iwvvV6U + r83KUCUnyMTCSICnBUPNwyrnBHg0uwWQKLQQhC6Ju6xUZ2kLivUVldW1hobGpuaWFqOx + tbW1DacCa0ZjS0tzU2ODoba6skJfXKDNUisvx0kQfAiNQsJK/tikRxkPfY7KYAG6VJ6U + diUnD8irausb77TeNbV3dHSa7+Fc5s6OjnbT3dY7jfW1VUCfl3MlLUkuBXgWg4r63QmB + PwdhR+hMNk8okSepNFpdCZA3NLeaOsz3LQ+6e6zWP3Auq7Wn+4HlvrnD1NrcAPQlOq1G + lSSXCHlsmOrIgdDrj0t6LOwkCp0ZzhWI4wA9t1B/q6a+ua3dbOm29vb122wDg0M41+CA + zdbf12vttpjb25rra27pC3MBPk4s4IYz6Sjrjw28O+xQ7Pxo2eU0TW5RaWVdo9F0z2J9 + 2D849GhkdHRsfNyOa42Pj42OjjwaGux/aLXcMxkb6ypLi3I1aZdl0Xwo+RMD7+sLjS6Y + zmRDsScor2gLS38zNLV1WHr6bMMjY/aJyanH06AZHAv5ezw1OWEfGxm29fVYOtqaDL+V + FmqvKBOg5NlMejAE3tf3SLdDKQ/VHoIyXp6kztHpKw1Nd81dvbbhUfvk9MzT2Wdzc3MO + h+M5bgXmwOKz2acz05P20WFbb5f5bpOhUq/LUSfJUdZjgT8m6SHl/VG1syNFsQpVZl7J + rVpA7+4bHLFPzszOPZ9fWFxaegF6iVshd0tLiwvzz+dmZybtI4N93QBfe6skL1OliBWh + wFNI/sd0u3OQ8kFURhhHII5PydAWV9TcbgP0odGJ6VnHwtLL5Vcrq5jWcCuXv5VXyy+X + Fhyz0xOjQwDfdrumolibkRIvFnDCGNQgSPojnR5LeRrzIk8Uo1BlFeir6o0dDwB98snc + /Ivl1bX1jY3Nra2tbVwLDG5ubKyvrS6/mJ97MgnwDzqM9VX6giyVIkbEu8ikwTTnd6Tg + sZSHZQ0/Oi5ZDWGvbTZZegcB3bG4vLq+ub392vnmTMj5ent7c311edEB8IO9FlNzLQRe + nRwHrZ7FwJL+ULODckcpH86NkiakavL1VQ1t5h7byMQTx9Ly2ua2883O7p5L+7iV2+Du + zhvn9uba8pLjycSIrcfc1lClz9ekJkijuOEo6Y8UPCp3MjX0YqRIlpieUwRhb7f0Ddun + 5xZfrW85d/b29t++OyN6u7+3t+PcWn+1ODdtH+6ztEPgi3LSE2WiyIuhVPLRggf2QDKN + CSkvT1bnXq+sbzVbbaNTs/PLa1vO3T0Af/836APOhTy+f/fu7d6uc2tteX52atRmNbfW + V17PVSfLIemxgj/c7M7B7E5hsDgCSbxSk6evbjRZHg7bZxxLq5vO3X0A90D/g2N5PAL+ + /q5zc3XJMWMffmgxNVbr8zTKeImAAwUPze5Qo/f18ycFQ7kLpQpVtq689k5Hd//I5OzC + 8vr2m7137+Gqh5g/4kiHrIHZ9+/23myvLy/MTo70d3fcqS3XZasUUiEUfDDJ/3CjB/Yg + WNTxRLFQ7sU3DUazdWBsem5pZcO5+/YQOo6oP7Py2QAg+Le7zo2VpbnpsQGr2Wi4WQwF + HyviwdIu6Cg7avPQ6n6RJam11yob2u73Dtlnnr9c3YKwQ8J/duV/PvtCHP3zc4cfPvwN + gd9affl8xj7Ue7+tofKaVp0k+wU1O9To/zvJwRRHpjLZMLunZFwtqbptsvT9NfF0HlJ+ + Zx/YPRfGEeuxVjw+gX1/B5J+/unEX30W0+2qkqsZKTDDs5nQ6I+yu9q8GLW6G9VN7V1/ + PkLlvvF6dx9S3n3NY78PV//pNgpJv7/7egMV/KM/u9qbqm+gZid2Nfoj7DDF0WGKQ20+ + X1/T/Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpgp8Oq9nDOI3ZW + hABWdZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1NakAkrO0EE60R2 + Dqxo07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeVBqtazgnsFLiB + jcKm97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxujuY8sHuWNmh6 + B3bHiwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQUQgLuxgh + 9xTsrT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S9I6ta93z + +4+Iu5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W2M8uiPrM + 6jyBn1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad/XcLu07z + biGR3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/YvcBY1qPt + 7wTcAw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNFHg7yIuKZ + TrCbAnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2BndSJ4Nz7E + n3BntLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I/BQj8C9p + pK71CmVuZHN0cmVhbQplbmRvYmoKMzkgMCBvYmoKMjc2MAplbmRvYmoKMzYgMCBvYmoK + PDwgL0xlbmd0aCAzNyAwIFIgL1R5cGUgL1hPYmplY3QgL1N1YnR5cGUgL0ltYWdlIC9X + aWR0aCAyNTIgL0hlaWdodCAxMDQgL0NvbG9yU3BhY2UKL0RldmljZUdyYXkgL0JpdHNQ + ZXJDb21wb25lbnQgOCAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAHtnPlX + Uukfx01LRZBFQUPAQBgBRZRcUDwYLoOpqGW4lKNH5aupiXZwlDqYMuaIy+TCUdMyyaXM + 3cilmub0r83nuUA2LmXf+uHa5f2LnTjn8n49n+V57uU+j4+PV94R8I6AdwS8I+AdARiB + c2dGPyxciNj3k/xwrk9GfZHv7xkEN7Wf3/nz5y+cIYFdPz9sGP5PfgwcsBGzf0BAoEck + 3MrjMDAgwB+5dg3AN+O7wFG0/YGaRAoigyigYFwLOUROg0ikwEA0AJAAEP9vwkcVjiLu + D9yATQmmUmk0Op1xBkSn02hUajAMQRDwI3yM/rSlj4IO5BBxEpkM2MAcEspkslhhYWHh + uBYYZLGYzNAQBoMOA0Amk1D0Ef0pQ+8ivxAQGESmUGkIG4jZERERHA6Xy+XhWGCPwwGj + 7PDwMDQANCqFHBQY4Ir9abq+Cx3FPJhKD2Gywi9GcHi8S3y+QBAlxL2iBAI+/xKPx4m4 + GM5ihtAh+BB7V+i/lvco3yHdgZyCyAGcF8kXCEXR0WKJVCqNcSkWd3IbA4sScXS0SCjg + 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 + /Hu3bWTq2eIKsEO5nxn0jx898FDwrzdWFp9Njdi6f2+ugdUNNHpgp8Oq9nDOI3ZWhABW + dZkFpTXQ5m2jj6HVbTr3PrHjKsAnmnHBQ7Pbc25Cs3s8aoNGX1NakAkrO0EE60R2Dqxo + 07J0ZbUtnT0DiB1md9TqsOud+G04+wAzi5odmuGBfaCns6W2TJeVBqtazgnsFLiBjcKm + 97K6FrN1EE1x7jaPLoczwi/YQW7djR5NcoNWc0tdGTbBR8FtLCxujuY8sHuWNmh6B3bH + iwP2L3wX7j46YH/hwNiNBs/i5kvscPOeXVhhMN77Y2j852AfH/rjntFQUQgLuxgh9xTs + rT8Xe6uX3Rv3E3udu94P5zzu2tlXDHn6PPQ6VO/flfNf+Srcffwj2c/S9I6ta93z+4+I + u5cdd6l9gqH/rG2+ud4JubZxPa4j4pr24F6m82e6l+n86r0M3L8T9h6W2M8uiPrM6jyB + n1US+hk1gX+bIPJvUgT+LZLIv0ET+t0DQr9zQtx3jXwI/I6Zz3HvFnad/XcLu07zbiGR + 3ykl9rvExH2H3IfAewd8iLxnhMh7hTyBJ+IeMWAn7t5A6HaE3ROKAk/YvcBY1qPt7wTc + Aw7sUPIE3fuP4KHkCXnmAxxS5zrhJYiAZ30cwBPwjBc4ndAVeSKe7YNFHg7yIuKZTrCb + AnV7OL+NiGd5AbyLnohnuLlCj8WeeGf3IXgIPdAT8cxGtIfKhY8qn2BndSJ4Nz7En3Bn + tLrwIfxYAmCnvaJhwLfcNuEP8u1G+P4/6GJnQ9/P6r2CdwS8I+AdAe8I/BQj8C9ppK71 + CmVuZHN0cmVhbQplbmRvYmoKMzcgMCBvYmoKMjc2MAplbmRvYmoKNDYgMCBvYmoKPDwg + L0xlbmd0aCA0NyAwIFIgL04gMSAvQWx0ZXJuYXRlIC9EZXZpY2VHcmF5IC9GaWx0ZXIg + L0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4AYVST0gUURz+zTYShIhBhXiIdwoJlSmsrKDa + dnVZlW1bldKiGGffuqOzM9Ob2TXFkwRdojx1D6JjdOzQoZuXosCsS9cgqSAIPHXo+83s + 6iiEb3k73/v9/X7fe0RtnabvOylBVHNDlSulp25OTYuDHylFHdROWKYV+OlicYyx67mS + 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 + gQc1LhFnhxB0iPJwboTKvcL1/8i0x/raOvyt2x8WYW0HY0FYZiwg2JQoT/S14+ml9/fa + EOT4QHMczMN+EWx+BGPi+uG6ESEFDIAbXI35AC8gCXBAF+j9fcXAPAYeB8OzXiAclps+ + kPsjZX8w9vtfWpLA+8Be5IFOAJyVw0DQSb/kMNjWv1v3gC1HgEBYLgKEydTJzMrs/CND + 9Bp44PmPlul/MIfWDld4KOsHPGGpPzzR/gFP9B7U5B1ZFByjYu+LFEbKIRWROkh1pAYS + CzBINJIDSCIVkMpIbaQmUhWew76cb5v/Zy2H++P+z32a/lkzvHL8P+x/eAV+8HeMg/od + 3mlABp+P0tNE9Eholtj9WyN4RROIhG5wSEyYn48vAaMNf73wksAY4z2kJDByMjJY8D+q + bG8vCmVuZHN0cmVhbQplbmRvYmoKNDkgMCBvYmoKMzkxMAplbmRvYmoKMzEgMCBvYmoK + WyAvSUNDQmFzZWQgNDggMCBSIF0KZW5kb2JqCjUwIDAgb2JqCjw8IC9MZW5ndGggNTEg + MCBSIC9OIDMgL0FsdGVybmF0ZSAvRGV2aWNlUkdCIC9GaWx0ZXIgL0ZsYXRlRGVjb2Rl + ID4+CnN0cmVhbQp4Aa1YZ1QUy7auHgaGnBkyDFFyRhhyjkNOSlByZkhDDgqCICBBlCQi + CCiCIiDpYCCoiCiCgogKqIgKEiQISH49cDx33XfXXe/Pq7Wm66uvdqiuXd17dgPAgHEL + CQlEAACC8IQwa0MdzLHjjhjUO4AEVIAVqAION4/wEG1LSxws8l/a+iiAiFPDkkRb50Jk + 7PQDR6ZD8cE5Ketrhv9F6Q9NGwY7BACSgAlmn0OsRcTuh9iWiKMIIQRYxpeIPXzdPGEc + D2OJMFtrXRjXwJjW5xC3E7H7Ie4j4kgPH6LuGABkjHhPPzwAqHkYa3h6hXvA00S/np7h + HkEwzgUAoRMUFAzbpx+BeRGPkDBYl34HxoLEfYF7uLnOAKDMDNuw/hcXchSAJngb+Tj/ + xQm1AYBGAlDX/i9u1fpgryD0YLi3vNyBOYhaBwDSyf39VWF4bRcA2M3b39++tr+/WwkA + yTgAXYEeEWGRB7LwjUADAPxf48N7/luDBA4OMcB8IAzMQ8kIVRIhpDVpHUqJfIPyNw0T + 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 + 9Eholtj9WyN4RROIhG5wSEyYn48vAaMNf73wksAY4z2kJDByMjJY8D+qbG8vCmVuZHN0 + cmVhbQplbmRvYmoKNTEgMCBvYmoKMzkxMAplbmRvYmoKMjggMCBvYmoKWyAvSUNDQmFz + ZWQgNTAgMCBSIF0KZW5kb2JqCjUyIDAgb2JqCjw8IC9MZW5ndGggNTMgMCBSIC9OIDMg + L0FsdGVybmF0ZSAvRGV2aWNlUkdCIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVh + bQp4AYWUTUgUYRjH/7ONBLEG0ZcIxdDBJFQmC1IC0/UrU7Zl1UwJYp19d50cZ6eZ3S1F + IoTomHWMLlZEh4hO4aFDpzpEBJl1iaCjRRAFXiK2/zuTu2NUvjAzv3me//t8vcMAVY9S + jmNFNGDKzrvJ3ph2enRM2/waVahGFFwpw3M6EokBn6mVz/Vr9S0UaVlqlLHW+zZ8q3aZ + EFA0KndkAz4seTzg45Iv5J08NWckGxOpNNkhN7hDyU7yLfLWbIjHQ5wWngFUtVOTMxyX + cSI7yC1FIytjPiDrdtq0ye+lPe0ZU9Sw38g3OQvauPL9QNseYNOLim3MAx7cA3bXVWz1 + NcDOEWDxUMX2PenPR9n1ysscavbDKdEYa/pQKn2vAzbfAH5eL5V+3C6Vft5hDtbx1DIK + btHXsjDlJRDUG+xm/OQa/YuDnnxVC7DAOY5sAfqvADc/AvsfAtsfA4lqYKgVkctsN7jy + 4iLnAnTmnGnXzE7ktWZdP6J18GiF1mcbTQ1ayrI03+VprvCEWxTpJkxZBc7ZX9t4jwp7 + eJBP9he5JLzu36zMpVNdnCWa2NantOjqJjeQ72fMnj5yPa/3GbdnOGDlgJnvGwo4csq2 + 4jwXqYnU2OPxk2TGV1QnH5PzkDznFQdlTN9+LnUiQa6lPTmZ65eaXdzbPjMxxDOSrFgz + E53x3/zGLSRl3n3U3HUs/5tnbZFnGIUFARM27zY0JNGLGBrhwEUOGXpMKkxapV/QasLD + 5F+VFhLlXRYVvVjhnhV/z3kUuFvGP4VYHHMN5Qia/k7/oi/rC/pd/fN8baG+4plzz5rG + q2tfGVdmltXIuEGNMr6sKYhvsNoOei1kaZ3iFfTklfWN4eoy9nxt2aPJHOJqfDXUpQhl + asQ448muZfdFssU34edby/av6VH7fPZJTSXXsrp4Zin6fDZcDWv/s6tg0rKr8OSNkC48 + a6HuVQ+qfWqL2gpNPaa2q21qF9+OqgPlHcOclYkLrNtl9Sn2YGOa3spJV2aL4N/CL4b/ + pV5hC9c0NPkPTbi5jGkJ3xHcNnCHlP/DX7MDDd4KZW5kc3RyZWFtCmVuZG9iago1MyAw + IG9iago3OTIKZW5kb2JqCjcgMCBvYmoKWyAvSUNDQmFzZWQgNTIgMCBSIF0KZW5kb2Jq + CjI3IDAgb2JqCjw8IC9MZW5ndGggNTQgMCBSIC9GdW5jdGlvblR5cGUgMCAvQml0c1Bl + clNhbXBsZSA4IC9TaXplIFsgMTM2NSBdIC9Eb21haW4KWyAwIDEgXSAvUmFuZ2UgWyAw + IDEgMCAxIDAgMSBdIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlID4+CnN0cmVhbQp4AZXB10IB + AAAAwP//lYoQkTQUGVFpJxqUSjRUKBlf4OHuptO5JmiM/tEI/aFfNEQD1Ec/6Bt9oR76 + RB/oHb2hLuqgV9R2L+gZPaEWekQPqIka6B7doVt0g+qohq5RFV2hS3SBztGZO0Un6BhV + 0BE6RAeojEpoHxVRAeVRDu2hLMqgXbSD0mjbbaFNtIFSaB0l0RpKoDhaRTEURSsogsIo + hJZREAXQElp0C3PMAGm/R/cKZW5kc3RyZWFtCmVuZG9iago1NCAwIG9iagoxNzcKZW5k + b2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9NZWRpYUJveCBbMCAwIDU3NiA3MzNd + IC9Db3VudCAxIC9LaWRzIFsgMiAwIFIgXSA+PgplbmRvYmoKNTUgMCBvYmoKPDwgL1R5 + cGUgL0NhdGFsb2cgL1BhZ2VzIDMgMCBSIC9WZXJzaW9uIC8xLjQgPj4KZW5kb2JqCjU2 + IDAgb2JqCjw8IC9MZW5ndGggNTcgMCBSIC9MZW5ndGgxIDExMjE2IC9GaWx0ZXIgL0Zs + YXRlRGVjb2RlID4+CnN0cmVhbQp4Ab16e2CT1dn4c857zbVJmnuTJmmapOklvdHS0kJj + acu1FahCixTbQrkJWrFWQWFVUaQiE5GL4Jx44TptKBWCDH+MocDmp+gUlKlzn+jcPju3 + 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 + E7K7P73I9SrJBR9L8B0/pLPkgOt3hXmuzwqjlPS7jgWiLCY/S8dSOMV11Pm06/8457te + xbA32bQniD0OuHY7F7s2pEfJ1n7X45KT3e9an0zudOKrB1xLgptccwvl9smbonRvv6sc + 26eHVa7SMo+rxHnelR+IigTLec7JruzC/3Bl4ovYzY2D+sJ6l8O5wTUKm9KdtYFRGA6T + PWQbZJNt/b6Jrlcwi+junxAs2xQl9+wfn1Xoi5Ll4dLxWZuC4wO+4GSXL1gXCGB++klh + lXCTcJ1QJOTgxSY0uEKaYBQNok7UimpRKYqiECU/6a9y8YfJXqhCsuzdL/IifkJ4CSvZ + w+RFufLFgyIrUhFEYzTxCV66JIBbjL0DKGYEMHOAl3N8lLyI35KkqhfDLhR5AqzcoEPJ + w2N7FC8UUEpEChPxBsmjUR4eNHdXWasMY/TldTX/W9Qqt1yJZRP/zyMrcUY24R2GyB5n + M14XwUzC2XylK6ru/8ev607s0FGdk4Oqe39356J58vUXb21HK96CiTzSjdeRetrd7n2L + Oofu9vhb2+cskO5ftHVEOr0dNZFF3hr3vm75Pan6quZ5UnO3t2YfzKu9oWnfvHBHTX93 + uLtWuga0v716acs1c60Znmtp9T+Zq1oabKk0V7v83j/M1SI1t0tztUhztUhztYfb5bkk + EtQubKy+owulE6/I4BWVrMbIhKkzm/AmWHNNlOyQ7s3cCf8Nq6YP6wplbmRzdHJlYW0K + ZW5kb2JqCjU3IDAgb2JqCjc1NjgKZW5kb2JqCjU4IDAgb2JqCjw8IC9UeXBlIC9Gb250 + RGVzY3JpcHRvciAvQXNjZW50IDc3MCAvQ2FwSGVpZ2h0IDcyNyAvRGVzY2VudCAtMjMw + IC9GbGFncyAzMgovRm9udEJCb3ggWy05NTEgLTQ4MSAxNDQ1IDExMjJdIC9Gb250TmFt + ZSAvTlpFUlZQK0hlbHZldGljYSAvSXRhbGljQW5nbGUgMAovU3RlbVYgOTggL01heFdp + ZHRoIDE1MDAgL1N0ZW1IIDg1IC9YSGVpZ2h0IDUzMSAvRm9udEZpbGUyIDU2IDAgUiA+ + PgplbmRvYmoKNTkgMCBvYmoKWyAyNzggMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAw + IDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMAowIDcyMiAwIDAg + MCA3MjIgMjc4IDAgMCAwIDgzMyAwIDAgNjY3IDAgMCA2NjcgNjExIDAgMCAwIDAgMCAw + IDAgMCAwIDAgMCAwCjU1NiA1NTYgNTAwIDU1NiA1NTYgMCA1NTYgNTU2IDIyMiAwIDAg + MjIyIDgzMyA1NTYgNTU2IDU1NiAwIDMzMyA1MDAgMjc4IDU1NgowIDAgMCA1MDAgMCAw + IDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAg + MCAwIDAgMCAwCjAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAw + IDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAKMCAwIDAgMCAwIDAgMCAwIDAg + MCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCA1MDAgXQpl + bmRvYmoKMjYgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1RydWVUeXBlIC9C + YXNlRm9udCAvTlpFUlZQK0hlbHZldGljYSAvRm9udERlc2NyaXB0b3IKNTggMCBSIC9X + aWR0aHMgNTkgMCBSIC9GaXJzdENoYXIgMzIgL0xhc3RDaGFyIDIyMiAvRW5jb2Rpbmcg + L01hY1JvbWFuRW5jb2RpbmcKPj4KZW5kb2JqCjEgMCBvYmoKPDwgL1RpdGxlIChVbnRp + dGxlZCkgL0F1dGhvciAoRG91Z2xhcyBHcmVnb3IpIC9DcmVhdG9yIChPbW5pR3JhZmZs + ZSBQcm9mZXNzaW9uYWwpCi9Qcm9kdWNlciAoTWFjIE9TIFggMTAuNS43IFF1YXJ0eiBQ + REZDb250ZXh0KSAvQ3JlYXRpb25EYXRlIChEOjIwMDkwNjAzMTUyMjEwWjAwJzAwJykK + L01vZERhdGUgKEQ6MjAwOTA2MDMxNTIyMTBaMDAnMDAnKSA+PgplbmRvYmoKeHJlZgow + IDYwCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDA1Njk0NCAwMDAwMCBuIAowMDAwMDAy + MDU1IDAwMDAwIG4gCjAwMDAwNDgyNTAgMDAwMDAgbiAKMDAwMDAwMDAyMiAwMDAwMCBu + IAowMDAwMDAyMDM1IDAwMDAwIG4gCjAwMDAwMDIxNTkgMDAwMDAgbiAKMDAwMDA0Nzg1 + NCAwMDAwMCBuIAowMDAwMDAyNTc4IDAwMDAwIG4gCjAwMDAwMDUzMjEgMDAwMDAgbiAK + MDAwMDAwMjQzMSAwMDAwMCBuIAowMDAwMDA1MzQxIDAwMDAwIG4gCjAwMDAwMDU4OTAg + MDAwMDAgbiAKMDAwMDAwNTkxMCAwMDAwMCBuIAowMDAwMDA2NDU5IDAwMDAwIG4gCjAw + MDAwMDgxODYgMDAwMDAgbiAKMDAwMDAwODczNSAwMDAwMCBuIAowMDAwMDA2NDc5IDAw + MDAwIG4gCjAwMDAwMDcwMjggMDAwMDAgbiAKMDAwMDAwODc1NSAwMDAwMCBuIAowMDAw + MDA5MzA0IDAwMDAwIG4gCjAwMDAwMDcwNDggMDAwMDAgbiAKMDAwMDAwNzU5NyAwMDAw + MCBuIAowMDAwMDA3NjE3IDAwMDAwIG4gCjAwMDAwMDgxNjYgMDAwMDAgbiAKMDAwMDAz + ODc2MCAwMDAwMCBuIAowMDAwMDU2NzY5IDAwMDAwIG4gCjAwMDAwNDc4OTAgMDAwMDAg + biAKMDAwMDA0NjkwMiAwMDAwMCBuIAowMDAwMDA5MzI0IDAwMDAwIG4gCjAwMDAwMTcy + MjYgMDAwMDAgbiAKMDAwMDA0MjgzMSAwMDAwMCBuIAowMDAwMDE3MjQ3IDAwMDAwIG4g + CjAwMDAwMjAxODEgMDAwMDAgbiAKMDAwMDAyOTA2NyAwMDAwMCBuIAowMDAwMDMyMDAx + IDAwMDAwIG4gCjAwMDAwMzQ5NzcgMDAwMDAgbiAKMDAwMDAzNzkxMSAwMDAwMCBuIAow + MDAwMDMyMDIyIDAwMDAwIG4gCjAwMDAwMzQ5NTYgMDAwMDAgbiAKMDAwMDAyNjExMiAw + MDAwMCBuIAowMDAwMDI5MDQ2IDAwMDAwIG4gCjAwMDAwMjAyMDIgMDAwMDAgbiAKMDAw + MDAyMzEzNiAwMDAwMCBuIAowMDAwMDIzMTU3IDAwMDAwIG4gCjAwMDAwMjYwOTEgMDAw + MDAgbiAKMDAwMDAzNzkzMiAwMDAwMCBuIAowMDAwMDM4NzQwIDAwMDAwIG4gCjAwMDAw + Mzg3OTcgMDAwMDAgbiAKMDAwMDA0MjgxMCAwMDAwMCBuIAowMDAwMDQyODY4IDAwMDAw + IG4gCjAwMDAwNDY4ODEgMDAwMDAgbiAKMDAwMDA0NjkzOSAwMDAwMCBuIAowMDAwMDQ3 + ODM0IDAwMDAwIG4gCjAwMDAwNDgyMzAgMDAwMDAgbiAKMDAwMDA0ODMzMyAwMDAwMCBu + IAowMDAwMDQ4Mzk3IDAwMDAwIG4gCjAwMDAwNTYwNTYgMDAwMDAgbiAKMDAwMDA1NjA3 + NyAwMDAwMCBuIAowMDAwMDU2MzEzIDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgNjAg + L1Jvb3QgNTUgMCBSIC9JbmZvIDEgMCBSIC9JRCBbIDxiYzVlZmZkZTlhMWUyZTllZTdk + YTA4ZDUwYzhlZDc4YT4KPGJjNWVmZmRlOWExZTJlOWVlN2RhMDhkNTBjOGVkNzhhPiBd + ID4+CnN0YXJ0eHJlZgo1NzE2NQolJUVPRgoxIDAgb2JqCjw8L0F1dGhvciAoRG91Z2xh + cyBHcmVnb3IpL0NyZWF0aW9uRGF0ZSAoRDoyMDA5MDYwMjE4MTkwMFopL0NyZWF0b3Ig + KE9tbmlHcmFmZmxlIFByb2Zlc3Npb25hbCA1LjEuMSkvTW9kRGF0ZSAoRDoyMDA5MDYw + MzE1MjIwMFopL1Byb2R1Y2VyIChNYWMgT1MgWCAxMC41LjcgUXVhcnR6IFBERkNvbnRl + eHQpL1RpdGxlIChQQ0hMYXlvdXQuZ3JhZmZsZSk+PgplbmRvYmoKeHJlZgoxIDEKMDAw + MDA1ODUyMyAwMDAwMCBuIAp0cmFpbGVyCjw8L0lEIFs8YmM1ZWZmZGU5YTFlMmU5ZWU3 + ZGEwOGQ1MGM4ZWQ3OGE+IDxiYzVlZmZkZTlhMWUyZTllZTdkYTA4ZDUwYzhlZDc4YT5d + IC9JbmZvIDEgMCBSIC9QcmV2IDU3MTY1IC9Sb290IDU1IDAgUiAvU2l6ZSA2MD4+CnN0 + YXJ0eHJlZgo1ODc0MAolJUVPRgo= + + QuickLookThumbnail + + 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 + BAALABcAOwAaYWNzcEFQUEwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPbWAAEAAAAA + 0y1hcHBsiXAwVUVs1ORxbm+PhPb1RwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA + AAAOclhZWgAAASwAAAAUZ1hZWgAAAUAAAAAUYlhZWgAAAVQAAAAUd3RwdAAAAWgAAAAU + Y2hhZAAAAXwAAAAsclRSQwAAAagAAAAOZ1RSQwAAAbgAAAAOYlRSQwAAAcgAAAAOdmNn + dAAAAdgAAAYSbmRpbgAAB+wAAAY+ZGVzYwAADiwAAABkZHNjbQAADpAAAAJCbW1vZAAA + ENQAAAAoY3BydAAAEPwAAAAkWFlaIAAAAAAAAGDoAAA4FAAABlJYWVogAAAAAAAAcDYA + ALICAAAhG1hZWiAAAAAAAAAltwAAFgQAAKu4WFlaIAAAAAAAAPNSAAEAAAABFs9zZjMy + AAAAAAABDEIAAAXe///zJgAAB5IAAP2R///7ov///aMAAAPcAADAbGN1cnYAAAAAAAAA + AQHNAABjdXJ2AAAAAAAAAAEBzQAAY3VydgAAAAAAAAABAc0AAHZjZ3QAAAAAAAAAAAAD + AQAAAgAAACEAcgDsAYICOwMlBFIFqwc3CPcK+A0TDzQRZhOKFZkXixlgGx8cqB4PH2Mg + tSILI2gkySYnJ4so8CpbK78tKS6NL/MxVDKuNAw1XzavOAA5RzqHO788+T4vP2tApEHe + QxdETEWHRr9H9kksSl9LkUzCTfJPIFBOUXRSnlPQVR9WdlfHWRlaa1u2XP5eSF+MYM9i + EmNUZJZl22cdaGFpqmrzbDxtiG7Mb/FxBXIWcyV0N3VJdlt3bHh8eY96n3uxfMJ91X7o + f/qBD4IlgzqEToVdhlaHOYgYiPeJ2Iq7i5yMfo1gjkKPIo//kNqRtZKRk2SUOJUKldmW + qJd0mFCZQ5o8mzWcK50dngue9Z/coL6hnaJ3o06kIqTzpb+mi6dVqByo4qmqqnqra6xl + rV+uWK9NsECxL7Icswaz7bTTtba2mLd2uFS5MroOuuu7ybylvYC+W78zwAnA4cG0wonD + W8QtxQDF08ajx3TIRckWyebKtcuHzFfNKM38zs/Pj9BI0PzRsdJs0ynT59So1WvWMNb3 + 177YhtlP2hba3duk3GrdLt3x3rHfeOBF4Rfh6uK244LkTOUR5dHmj+dI5/3oq+lU6fvq + mus369LsZuz67YruJO7P74bwQPD58bTycPMu8+30sPV39kP3E/fo+Mb5qvqS+4L8ef11 + /nX/UP//AAAAOADDAW4CNgMhBDcFhAbsCHMKHgvXDaoPeRFMExkU1haDGCUZrhslHHAd + sB7xIDQhfiLMJBglaSa6KBIpZCq2LAotXC6oL/AxPTJ8M7w0+zYwN1s4dTmOOqU7vzzX + Pew/AUAUQStCQUNURGhFekaMR55IsUnFStZL50z6ThNPSFCGUb1S9FQsVWBWjle/WO1a + GVtFXHFdm17IX/NhIGJSY4FksWXkZxBoI2kmaiprLGwvbTVuOm8/cEZxTnJXc2J0a3V5 + dol3l3ipeb560nvmfPN98n7hf8mAsoGcgouDdYRihU6GOYciiAeI6onMiq6LiIxijTiO + C47bj6qQfpFzkmSTVZRFlTGWGpcAl+KYwpmemnebTZwhnPKdwJ6On1mgIqDrobaihaN4 + pG6lZqZcp1CoQakvqhurBKvsrNOtt66br3uwXbE9sh2y/rPftMG1oLaEt2a4RrkmugW6 + 5LvAvJy9eb5WvzLADsDrwcnCpsOExGPFQ8YkxwfH68jJyaXKgMtbzDnNGM33ztnPuNCb + 0X3SYNNC1CPVBNXk1sXXo9iB2V7aOdsZ3ATc8N3g3sffsOCW4XniWuM75Brk9uXR5qrn + g+hb6TPqDOrl673sl+1z7lXvQPAx8S7yMvM49Eb1V/Zm93P4evl5+m37U/wr/PX9pf5G + /tn/RP+h//8AAAAkAHwBAgGVAkoDIAQbBSwGWAeWCOEKOQuTDO4OQw+PENESDBMyFEUV + QBYwFyAYEhkJGgQa+xv5HPUd9R7zH/Eg8SHuIugj3yTVJcgmuCenKJEpdypXKzgsEizu + LcYunC9wMEExETHdMqYzbzQ1NPY1uDZ5Nzk39zi0OXE6MDsAO9I8pT14Pk0/Ij/3QM1B + pEJ8Q1VEMUUMRetGykerSI5JcUpUSzlMHUz8TdhOs0+PUGpRSFIkUwFT3lS8VZxWe1db + WEBZJVoKWvJb3VzIXbJeml9+YFdhL2IKYuhjyGSqZY5mdGdcaERpKmoQavZr3GzAbaJu + hG9gcDxxF3H8cu1z43TWdcZ2s3eaeHt5WnoxewV71XyhfWp+LH7sf6uAaYEigduClYNP + hAyEy4WLhkyHDIfNiI+JUYoUitmLoIxqjTWOAY7Pj5+QcZFFkhqS8JPBlISVNpXplp6X + U5gLmMaZhJpHmw2b1pyhnXKeRp8bn/OgzqGoooWjZ6RFpRul7Ka6p4uoZKk/qh2q/qvi + rMutta6gr4ywd7FhskqzMrQZtP213ra7t6C4r7m/utS74rzyvgC/CsASwRvCIMMjxCPF + IcYexxnIE8kNygXK+8vyzPDOOM+T0OvSONOE1NbWL9eN2PTadNwI3bvflOGT47/mP+kX + 7GbwR/Uz+4T//wAAbmRpbgAAAAAAAAY2AACYZQAAWYUAAFMYAACL2gAAJ5oAABVgAABQ + DQAAVDkAAmj1AAIrhQABXCgAAwEAAAIAAAAYADIASgBfAHQAiACcAK4AwgDUAOYA+QEL + AR4BMgFGAVoBbwGFAZwBtAHNAegCBAIiAkICYwKJArEC3wMPA0EDdAOoA9wEEQRHBH8E + twTwBSoFZAWhBd4GHAZcBp0G3wcjB2oHsQf5CEUIkwjhCTEJhQnbCjUKkQrtC00LqwwM + DG4M0g03DZ8OBg5vDtoPRw+1ECYQmBENEYIR+hJ0Eu8TbxPuFHAU6RVbFc4WRRa8FzUX + rhgrGKoZKxmsGjEatxs+G8ccURzdHWgd9R6EHxMfoSAwIMEhUiHjInUjFiPGJH0lNSXw + JqonZigkKOQppipoKy0r8iy7LYMuTC8XL+QwsDF9Mk0zHzP3NOY18Db8OAo5FTomOzc8 + Sj1gPnw/nkDFQetDIURWRZZG2kglSVVKY0t6TJBNrk7ST/9RMFJsU7BU/VZRV69ZGVqH + W/xdfF76YGthnmLVZA1lSmaNZ9ZpJmp8a9dtOW6gcAtxgHL1dHB17XdqeOx6cnv7fY9/ + IYC/glqEAIWmh06I/IqtjF+OFY/RkYeTRpT/lrqYpJqynMCevaC7orCko6aQqH6qa6xd + rlOwTLJMtFS2aLhmulK8O745wDfCSMRrxprI5ctNzc/QeNM31hvZFtuc3fPgT+Ko5P3n + UOmW687t+fAX8h70GfYK9+r5v/uQ/Vn//wAAAA4AIQA1AEkAXABvAIMAlwCrAL8A1ADp + AP4BFAErAUMBWwF1AY8BqwHIAecCBwIpAk0CdAKdAswC/gMzA2gDnwPWBA4ERwSCBL0E + +gU3BXUFtQX3BjkGfQbCBwoHUwefB+oIOgiMCN4JMwmMCegKTAqyCxsLhQvwDF4Mzw1B + DbYOKw6iDxwPlxAVEJURFhGZEh0SoxMsE7cUQRTKFUYVwhZCFsQXRxfLGFIY3RloGfUa + hRsWG6kcPRzUHWoeAh6cHzYfzyBrIQghpSJCIugjoSRiJSMl6CasJ3EoOCkBKcoqlCtf + LCos+C3ELpAvYDAuMPsxyjKbM240TDU9Nj03PjhBOUA6RjtLPFM9Xj5vP4dAo0HBQuxE + GUVRRo9H1kkWSilLSExmTYpOtE/mUR5SXVOkVPNWSFelWQ1aeFvpXWRe3WBQYYZiwWP8 + ZTtmgWfLaRxqc2vObS5ulG/7cWxy3HRRdcd3Pni2ejR7rH0sfq6ANYG9g06E4IZziAmJ + o4s8jNeOc5ASka2TTpTnloKYKZnXm4qdPJ7poJqiSKP8paqnXKkPqsasga4/r/6xxLOM + tVy3Lrjiupi8R74Kv8jBkcNkxTnHE8j3yuDM0M7B0LjSrNSk1qHYmdqM3GvePd/94a3j + XOUD5qHoQuno65btUO8b8QPzEPVR9+77DP//AAAAFgAwAEoAYwB9AJcAsQDNAOkBBgEk + AUQBZQGIAa0B1QH/AiwCXQKTAtEDFQNcA6UD7wQ6BIkE2AUqBX0F0wYrBoUG4gdDB6cI + Dgh5COcJWQnQCk4KzgtVC90MbAz/DZgONA7YD4AQLxDkEZ0SXBMfE+gUsxVuFisW6her + GG4ZNBn7GsQbjhxYHSUd8R6/H40gXCEvIgEi1yO1JJglfiZmJ04oOikoKhcrByv5LO0t + 3i7RL8YwuDGrMqAzmTSZNak2vTfPON457jr9PAw9GT4qPz5AVkFtQopDq0TQRf5HLkhk + SYRKmku0TNNN+U8oUGJRolLxVElVrVcZWJdaHVuoXUNe3GB5Yg5jpmU8ZtZocWoOa6lt + Qm7YcGtx/3OQdR52rHg3ecZ7f31nf0eBKYMChNSGnIhdihiLyY13jyOQx5JwlBOVsZda + mRya6JyxnmigHqHNo3ulH6bCqGWqB6uvrVmvB7C6snO0NLYCt8G5NbqyvCW9qL8lwKjC + McPBxU/G4sh9yhzLws1pzxfQytJ81DPV8det2W/ayNwL3Unejd/d4TDigePN5RbmXOee + 6NvqCest7EjtUu5Y703wPPEf8fzyzPOZ9FD1B/Wu9k727vd8+Af4k/kT+Yn6APp3+tz7 + OfuX+/T8Uvye/OX9Lf10/bz+BP5Y/sL/K/+V//8AAGRlc2MAAAAAAAAACkNvbG9yIExD + RAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA + AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABtbHVjAAAAAAAAABIAAAAMbmJOTwAA + ABIAAADocHRQVAAAABYAAAD6c3ZTRQAAABAAAAEQZmlGSQAAABAAAAEgZGFESwAAABwA + AAEwemhDTgAAAAwAAAFMZnJGUgAAABYAAAFYamFKUAAAAA4AAAFuZW5VUwAAABIAAAF8 + cGxQTAAAABIAAAGOcHRCUgAAABgAAAGgZXNFUwAAABIAAAG4emhUVwAAAA4AAAHKcnVS + VQAAACQAAAHYa29LUgAAAAwAAAH8ZGVERQAAABAAAAIIbmxOTAAAABYAAAIYaXRJVAAA + ABQAAAIuAEYAYQByAGcAZQAtAEwAQwBEAEwAQwBEACAAYQAgAEMAbwByAGUAcwBGAOQA + cgBnAC0ATABDAEQAVgDkAHIAaQAtAEwAQwBEAEwAQwBEAC0AZgBhAHIAdgBlAHMAawDm + AHIAbV9pgnIAIABMAEMARABMAEMARAAgAGMAbwB1AGwAZQB1AHIwqzDpMPwAIABMAEMA + RABDAG8AbABvAHIAIABMAEMARABLAG8AbABvAHIAIABMAEMARABMAEMARAAgAEMAbwBs + AG8AcgBpAGQAbwBMAEMARAAgAGMAbwBsAG8Acl9pgnJtsmZ2mG95OlZoBCYEMgQ1BEIE + PQQ+BDkAIAQWBBoALQQ0BDgEQQQ/BDsENQQ5zuy37AAgAEwAQwBEAEYAYQByAGIALQBM + AEMARABLAGwAZQB1AHIAZQBuAC0ATABDAEQATABDAEQAIABjAG8AbABvAHIAaQAAbW1v + ZAAAAAAAAAYQAACcgAAAAADDJekAAAAAAAAAAAAAAAAAAAAAAHRleHQAAAAAQ29weXJp + Z2h0IEFwcGxlLCBJbmMuLCAyMDA5AA== + + ReadOnly + NO + RowAlign + 1 + RowSpacing + 36 + SheetTitle + Canvas 1 + SmartAlignmentGuidesActive + YES + SmartDistanceGuidesActive + YES + UniqueID + 1 + UseEntirePage + + VPages + 1 + WindowInfo + + CurrentSheet + 0 + ExpandedCanvases + + + name + Canvas 1 + + + Frame + {{388, 0}, {710, 878}} + ListView + + OutlineWidth + 142 + RightSidebar + + ShowRuler + + Sidebar + + SidebarWidth + 120 + VisibleRegion + {{0, 0}, {561, 709}} + Zoom + 1 + ZoomValues + + + Canvas 1 + 1 + 1 + + + + saveQuickLookFiles + YES + + diff --git a/docs/main/PCHLayout.png b/docs/main/PCHLayout.png new file mode 100644 index 0000000000..c304e04a05 Binary files /dev/null and b/docs/main/PCHLayout.png differ diff --git a/docs/main/PTHInternals.html b/docs/main/PTHInternals.html new file mode 100644 index 0000000000..279d47968b --- /dev/null +++ b/docs/main/PTHInternals.html @@ -0,0 +1,177 @@ + + + Pretokenized Headers (PTH) + + + + + + + + +
    + +

    Pretokenized Headers (PTH)

    + +

    This document first describes the low-level +interface for using PTH and then briefly elaborates on its design and +implementation. If you are interested in the end-user view, please see the +User's Manual.

    + + +

    Using Pretokenized Headers with clang (Low-level Interface)

    + +

    The Clang compiler frontend, clang -cc1, supports three command line +options for generating and using PTH files.

    + +

    To generate PTH files using clang -cc1, use the option +-emit-pth: + +

     $ clang -cc1 test.h -emit-pth -o test.h.pth
    + +

    This option is transparently used by clang when generating PTH +files. Similarly, PTH files can be used as prefix headers using the +-include-pth option:

    + +
    +  $ clang -cc1 -include-pth test.h.pth test.c -o test.s
+
    + +

    Alternatively, Clang's PTH files can be used as a raw "token-cache" +(or "content" cache) of the source included by the original header +file. This means that the contents of the PTH file are searched as substitutes +for any source files that are used by clang -cc1 to process a +source file. This is done by specifying the -token-cache +option:

    + +
    +  $ cat test.h
+  #include <stdio.h>
+  $ clang -cc1 -emit-pth test.h -o test.h.pth
+  $ cat test.c
+  #include "test.h"
+  $ clang -cc1 test.c -o test -token-cache test.h.pth
+
    + +

    In this example the contents of stdio.h (and the files it includes) +will be retrieved from test.h.pth, as the PTH file is being used in +this case as a raw cache of the contents of test.h. This is a low-level +interface used to both implement the high-level PTH interface as well as to +provide alternative means to use PTH-style caching.

    + +

    PTH Design and Implementation

    + +

    Unlike GCC's precompiled headers, which cache the full ASTs and preprocessor +state of a header file, Clang's pretokenized header files mainly cache the raw +lexer tokens that are needed to segment the stream of characters in a +source file into keywords, identifiers, and operators. Consequently, PTH serves +to mainly directly speed up the lexing and preprocessing of a source file, while +parsing and type-checking must be completely redone every time a PTH file is +used.

    + +

    Basic Design Tradeoffs

    + +

    In the long term there are plans to provide an alternate PCH implementation +for Clang that also caches the work for parsing and type checking the contents +of header files. The current implementation of PCH in Clang as pretokenized +header files was motivated by the following factors:

    + +

      + +

    • Language independence: PTH files work with any language that +Clang's lexer can handle, including C, Objective-C, and (in the early stages) +C++. This means development on language features at the parsing level or above +(which is basically almost all interesting pieces) does not require PTH to be +modified.

      • + +
    • Simple design: Relatively speaking, PTH has a simple design and +implementation, making it easy to test. Further, because the machinery for PTH +resides at the lower-levels of the Clang library stack it is fairly +straightforward to profile and optimize.
      • +
    + +

    Further, compared to GCC's PCH implementation (which is the dominate +precompiled header file implementation that Clang can be directly compared +against) the PTH design in Clang yields several attractive features:

    + +
      + +

    • Architecture independence: In contrast to GCC's PCH files (and +those of several other compilers), Clang's PTH files are architecture +independent, requiring only a single PTH file when building an program for +multiple architectures.

      + +

      For example, on Mac OS X one may wish to +compile a "universal binary" that runs on PowerPC, 32-bit Intel +(i386), and 64-bit Intel architectures. In contrast, GCC requires a PCH file for +each architecture, as the definitions of types in the AST are +architecture-specific. Since a Clang PTH file essentially represents a lexical +cache of header files, a single PTH file can be safely used when compiling for +multiple architectures. This can also reduce compile times because only a single +PTH file needs to be generated during a build instead of several.

      • + +

    • Reduced memory pressure: Similar to GCC, +Clang reads PTH files via the use of memory mapping (i.e., mmap). +Clang, however, memory maps PTH files as read-only, meaning that multiple +invocations of clang -cc1 can share the same pages in memory from a +memory-mapped PTH file. In comparison, GCC also memory maps its PCH files but +also modifies those pages in memory, incurring the copy-on-write costs. The +read-only nature of PTH can greatly reduce memory pressure for builds involving +multiple cores, thus improving overall scalability.

      • + +

    • Fast generation: PTH files can be generated in a small fraction +of the time needed to generate GCC's PCH files. Since PTH/PCH generation is a +serial operation that typically blocks progress during a build, faster +generation time leads to improved processor utilization with parallel builds on +multicore machines.

      • + +
    + +

    Despite these strengths, PTH's simple design suffers some algorithmic +handicaps compared to other PCH strategies such as those used by GCC. While PTH +can greatly speed up the processing time of a header file, the amount of work +required to process a header file is still roughly linear in the size of the +header file. In contrast, the amount of work done by GCC to process a +precompiled header is (theoretically) constant (the ASTs for the header are +literally memory mapped into the compiler). This means that only the pieces of +the header file that are referenced by the source file including the header are +the only ones the compiler needs to process during actual compilation. While +GCC's particular implementation of PCH mitigates some of these algorithmic +strengths via the use of copy-on-write pages, the approach itself can +fundamentally dominate at an algorithmic level, especially when one considers +header files of arbitrary size.

    + +

    There are plans to potentially implement an complementary PCH implementation +for Clang based on the lazy deserialization of ASTs. This approach would +theoretically have the same constant-time algorithmic advantages just mentioned +but would also retain some of the strengths of PTH such as reduced memory +pressure (ideal for multi-core builds).

    + +

    Internal PTH Optimizations

    + +

    While the main optimization employed by PTH is to reduce lexing time of +header files by caching pre-lexed tokens, PTH also employs several other +optimizations to speed up the processing of header files:

    + +
      + +

    • stat caching: PTH files cache information obtained via +calls to stat that clang -cc1 uses to resolve which files are +included by #include directives. This greatly reduces the overhead +involved in context-switching to the kernel to resolve included files.

      • + +

    • Fasting skipping of #ifdef...#endif chains: +PTH files record the basic structure of nested preprocessor blocks. When the +condition of the preprocessor block is false, all of its tokens are immediately +skipped instead of requiring them to be handled by Clang's +preprocessor.

      • + +
    + +
    + + diff --git a/docs/main/UsersManual.html b/docs/main/UsersManual.html new file mode 100644 index 0000000000..4ba00e0b9a --- /dev/null +++ b/docs/main/UsersManual.html @@ -0,0 +1,904 @@ + + +Clang Compiler User's Manual + + + + + + + + +
    + +

    Clang Compiler User's Manual

    + + + + + +

    Introduction

    + + +

    The Clang Compiler is an open-source compiler for the C family of programming +languages, aiming to be the best in class implementation of these languages. +Clang builds on the LLVM optimizer and code generator, allowing it to provide +high-quality optimization and code generation support for many targets. For +more general information, please see the Clang +Web Site or the LLVM Web Site.

    + +

    This document describes important notes about using Clang as a compiler for +an end-user, documenting the supported features, command line options, etc. If +you are interested in using Clang to build a tool that processes code, please +see the Clang Internals Manual. If you are +interested in the Clang +Static Analyzer, please see its web page.

    + +

    Clang is designed to support the C family of programming languages, which +includes C, Objective-C, C++, and Objective-C++ as well as many +dialects of those. For language-specific information, please see the +corresponding language specific section:

    + + + +

    In addition to these base languages and their dialects, Clang supports a +broad variety of language extensions, which are documented in the corresponding +language section. These extensions are provided to be compatible with the GCC, +Microsoft, and other popular compilers as well as to improve functionality +through Clang-specific features. The Clang driver and language features are +intentionally designed to be as compatible with the GNU GCC compiler as +reasonably possible, easing migration from GCC to Clang. In most cases, code +"just works".

    + +

    In addition to language specific features, Clang has a variety of features +that depend on what CPU architecture or operating system is being compiled for. +Please see the Target-Specific Features and +Limitations section for more details.

    + +

    The rest of the introduction introduces some basic compiler terminology that is used throughout this manual +and contains a basic introduction to using Clang +as a command line compiler.

    + + +

    Terminology

    + + +

    Front end, parser, backend, preprocessor, undefined behavior, diagnostic, + optimizer

    + + +

    Basic Usage

    + + +

    Intro to how to use a C compiler for newbies.

    +

    +compile + link + +compile then link + +debug info + +enabling optimizations + +picking a language to use, defaults to C99 by default. Autosenses based on +extension. + +using a makefile +

    + + + +

    Command Line Options

    + + +

    +This section is generally an index into other sections. It does not go into +depth on the ones that are covered by other sections. However, the first part +introduces the language selection and other high level options like -c, -g, etc. +

    + + + +

    Options to Control Error and Warning Messages

    + + +

    -Werror: Turn warnings into errors.

    +

    -Werror=foo: Turn warning "foo" into an error.

    +

    -Wno-error=foo: Turn warning "foo" into an warning even if -Werror is + specified.

    +

    -Wfoo: Enable warning foo

    +

    -Wno-foo: Disable warning foo

    +

    -w: Disable all warnings.

    +

    -pedantic: Warn on language extensions.

    +

    -pedantic-errors: Error on language extensions.

    +

    -Wsystem-headers: Enable warnings from system headers.

    + +

    -ferror-limit=123: Stop emitting diagnostics after 123 errors have + been produced. The default is 20, and the error limit can be disabled with + -ferror-limit=0.

    + +

    -ftemplate-backtrace-limit=123: Only emit up to 123 template instantiation notes within the template instantiation backtrace for a single warning or error. The default is 10, and the limit can be disabled with -ftemplate-backtrace-limit=0.

    + + +

    Formatting of Diagnostics

    + + +

    Clang aims to produce beautiful diagnostics by default, particularly for new +users that first come to Clang. However, different people have different +preferences, and sometimes Clang is driven by another program that wants to +parse simple and consistent output, not a person. For these cases, Clang +provides a wide range of options to control the exact output format of the +diagnostics that it generates.

    + +
    + + +
    -f[no-]show-column: Print column number in +diagnostic.
    +
    This option, which defaults to on, controls whether or not Clang prints the +column number of a diagnostic. For example, when this is enabled, Clang will +print something like:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+  #endif bad
+         ^
+         //
+
    + +

    When this is disabled, Clang will print "test.c:28: warning..." with no +column number.

    +
    + + +
    -f[no-]show-source-location: Print +source file/line/column information in diagnostic.
    +
    This option, which defaults to on, controls whether or not Clang prints the +filename, line number and column number of a diagnostic. For example, +when this is enabled, Clang will print something like:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+  #endif bad
+         ^
+         //
+
    + +

    When this is disabled, Clang will not print the "test.c:28:8: " part.

    +
    + + +
    -f[no-]caret-diagnostics: Print source +line and ranges from source code in diagnostic.
    +
    This option, which defaults to on, controls whether or not Clang prints the +source line, source ranges, and caret when emitting a diagnostic. For example, +when this is enabled, Clang will print something like:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+  #endif bad
+         ^
+         //
+
    + +

    When this is disabled, Clang will just print:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+
    + +
    + + +
    -f[no-]diagnostics-show-option: +Enable [-Woption] information in diagnostic line.
    +
    This option, which defaults to on, +controls whether or not Clang prints the associated warning group option name when outputting +a warning diagnostic. For example, in this output:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+  #endif bad
+         ^
+         //
+
    + +

    Passing -fno-diagnostics-show-option will prevent Clang from printing +the [-Wextra-tokens] information in the +diagnostic. This information tells you the flag needed to enable or disable the +diagnostic, either from the command line or through #pragma GCC diagnostic.

    + + +
    -fdiagnostics-show-category=none/id/name: +Enable printing category information in diagnostic line.
    +
    This option, which defaults to "none", +controls whether or not Clang prints the category associated with a diagnostic +when emitting it. Each diagnostic may or many not have an associated category, +if it has one, it is listed in the diagnostic categorization field of the +diagnostic line (in the []'s).

    + +

    For example, a format string warning will produce these three renditions +based on the setting of this option:

    + +
    +  t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+  t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+  t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
+
    + +

    This category can be used by clients that want to group diagnostics by +category, so it should be a high level category. We want dozens of these, not +hundreds or thousands of them.

    +
    + + + + +
    -f[no-]diagnostics-fixit-info: +Enable "FixIt" information in the diagnostics output.
    +
    This option, which defaults to on, controls whether or not Clang prints the +information on how to fix a specific diagnostic underneath it when it knows. +For example, in this output:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+  #endif bad
+         ^
+         //
+
    + +

    Passing -fno-diagnostics-fixit-info will prevent Clang from printing +the "//" line at the end of the message. This information is useful for users +who may not understand what is wrong, but can be confusing for machine +parsing.

    +
    + + +
    +-f[no-]diagnostics-print-source-range-info: +Print machine parsable information about source ranges.
    +
    This option, which defaults to off, controls whether or not Clang prints +information about source ranges in a machine parsable format after the +file/line/column number information. The information is a simple sequence of +brace enclosed ranges, where each range lists the start and end line/column +locations. For example, in this output:

    + +
    +exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+   P = (P-42) + Gamma*4;
+       ~~~~~~ ^ ~~~~~~~
+
    + +

    The {}'s are generated by -fdiagnostics-print-source-range-info.

    +
    + + +
    + + + + + +

    Individual Warning Groups

    + + +

    TODO: Generate this from tblgen. Define one anchor per warning group.

    + + +
    + + + +
    -Wextra-tokens: Warn about excess tokens at + the end of a preprocessor directive.
    +
    This option, which defaults to on, enables warnings about extra tokens at +the end of preprocessor directives. For example:

    + +
    +  test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+  #endif bad
+         ^
+
    + +

    These extra tokens are not strictly conforming, and are usually best handled +by commenting them out.

    + +

    This option is also enabled by -Wfoo, -Wbar, + and -Wbaz.

    +
    + +
    + + +

    Language and Target-Independent Features

    + + + + +

    Controlling Errors and Warnings

    + + +

    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 +the ability to print this information, and these are the options that control +it:

    + +

    +

      +
    1. A file/line/column indicator that shows exactly where the diagnostic occurs + in your code [-fshow-column, -fshow-source-location].
      2. +
    2. A categorization of the diagnostic as a note, warning, error, or fatal + error.
      3. +
    3. A text string that describes what the problem is.
      4. +
    4. An option that indicates how to control the diagnostic (for diagnostics that + support it) [-fdiagnostics-show-option].
      5. +
    5. A high-level category for the diagnostic for clients that want to group + diagnostics by class (for diagnostics that + support it) [-fdiagnostics-show-category].
      6. +
    6. The line of source code that the issue occurs on, along with a caret and + ranges that indicate the important locations [-fcaret-diagnostics].
      7. +
    7. "FixIt" information, which is a concise explanation of how to fix the + problem (when Clang is certain it knows) [-fdiagnostics-fixit-info].
      8. +
    8. A machine-parsable representation of the ranges involved (off by + default) [-fdiagnostics-print-source-range-info].
      9. +

    + +

    For more information please see Formatting of +Diagnostics.

    + +

    Diagnostic Mappings

    + +

    All diagnostics are mapped into one of these 5 classes:

    + +

    +

      +
    • Ignored
      • +
    • Note
      • +
    • Warning
      • +
    • Error
      • +
    • Fatal
      • +

    + +

    Controlling Diagnostics via Command Line Flags

    + +

    -W flags, -pedantic, etc

    + +

    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:

    + +
    +#pragma GCC diagnostic ignored "-Wall"
+
    + +

    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.

    + +
    +#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wmultichar"
+
+char b = 'df'; // no warning.
+
+#pragma clang diagnostic pop
+
    + +

    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

    + + +

    Precompiled +headers are a general approach employed by many compilers to reduce +compilation time. The underlying motivation of the approach is that it is +common for the same (and often large) header files to be included by +multiple source files. Consequently, compile times can often be greatly improved +by caching some of the (redundant) work done by a compiler to process headers. +Precompiled header files, which represent one of many ways to implement +this optimization, are literally files that represent an on-disk cache that +contains the vital information necessary to reduce some of the work +needed to process a corresponding header file. While details of precompiled +headers vary between compilers, precompiled headers have been shown to be a +highly effective at speeding up program compilation on systems with very large +system headers (e.g., Mac OS/X).

    + +

    Generating a PCH File

    + +

    To generate a PCH file using Clang, one invokes Clang with +the -x <language>-header option. This mirrors the +interface in GCC for generating PCH files:

    + +
    +  $ gcc -x c-header test.h -o test.h.gch
+  $ clang -x c-header test.h -o test.h.pch
+
    + +

    Using a PCH File

    + +

    A PCH file can then be used as a prefix header when a +-include option is passed to clang:

    + +
    +  $ clang -include test.h test.c -o test
+
    + +

    The clang driver will first check if a PCH file for test.h +is available; if so, the contents of test.h (and the files it includes) +will be processed from the PCH file. Otherwise, Clang falls back to +directly processing the content of test.h. This mirrors the behavior of +GCC.

    + +

    NOTE: Clang does not automatically use PCH files +for headers that are directly included within a source file. For example:

    + +
    +  $ clang -x c-header test.h -o test.h.pch
+  $ cat test.c
+  #include "test.h"
+  $ clang test.c -o test
+
    + +

    In this example, clang will not automatically use the PCH file for +test.h since test.h was included directly in the source file +and not specified on the command line using -include.

    + +

    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:

    + +
    +  # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+
    + +

    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.

    + + +

    Controlling Code Generation

    + + +

    Clang provides a number of ways to control code generation. The options are listed below.

    + + +
    -fcatch-undefined-behavior: Turn +on runtime code generation to check for undefined behavior.
    + +
    This option, which defaults to off, controls whether or not Clang +adds runtime checks for undefined runtime behavior. If the check fails, +__builtin_trap() is used to indicate failure. +The checks are: +

    +

  • Subscripting where the static type of one operand is variable + which is decayed from an array type and the other operand is + greater than the size of the array or less than zero.
    • +
  • Shift operators where the amount shifted is greater or equal to the + promoted bit-width of the left-hand-side or less than zero.
    • +
  • If control flow reaches __builtin_unreachable. +
  • When llvm implements more __builtin_object_size support, reads and + writes for objects that __builtin_object_size indicates we aren't + accessing valid memory. Bit-fields and vectors are not yet checked. +

    +
    • + +
    -fno-assume-sane-operator-new: +Don't assume that the C++'s new operator is sane.
    +
    This option tells the compiler to do not assume that C++'s global new +operator will always return a pointer that do not +alias any other pointer when the function returns.
    + + +

    C Language Features

    + + +

    The support for standard C in clang is feature-complete except for the C99 +floating-point pragmas.

    + + +

    Extensions supported by clang

    + + +

    See clang language extensions.

    + + +

    Differences between various standard modes

    + + +

    clang supports the -std option, which changes what language mode clang uses. +The supported modes for C are c89, gnu89, c94, c99, gnu99 and various aliases +for those modes. If no -std option is specified, clang defaults to gnu99 mode. +

    + +

    Differences between all c* and gnu* modes:

    +
      +
    • c* modes define "__STRICT_ANSI__".
      • +
    • Target-specific defines not prefixed by underscores, like "linux", are +defined in gnu* modes.
      • +
    • Trigraphs default to being off in gnu* modes; they can be enabled by the +-trigraphs option.
      • +
    • The parser recognizes "asm" and "typeof" as keywords in gnu* modes; the +variants "__asm__" and "__typeof__" are recognized in all modes.
      • +
    • The Apple "blocks" extension is recognized by default in gnu* modes +on some platforms; it can be enabled in any mode with the "-fblocks" +option.
      • +
    + +

    Differences between *89 and *99 modes:

    +
      +
    • The *99 modes default to implementing "inline" as specified in C99, while +the *89 modes implement the GNU version. This can be overridden for individual +functions with the __gnu_inline__ attribute.
      • +
    • Digraphs are not recognized in c89 mode.
      • +
    • The scope of names defined inside a "for", "if", "switch", "while", or "do" +statement is different. (example: "if ((struct x {int x;}*)0) {}".)
      • +
    • __STDC_VERSION__ is not defined in *89 modes.
      • +
    • "inline" is not recognized as a keyword in c89 mode.
      • +
    • "restrict" is not recognized as a keyword in *89 modes.
      • +
    • Commas are allowed in integer constant expressions in *99 modes.
      • +
    • Arrays which are not lvalues are not implicitly promoted to pointers in +*89 modes.
      • +
    • Some warnings are different.
      • +
    + +

    c94 mode is identical to c89 mode except that digraphs are enabled in +c94 mode (FIXME: And __STDC_VERSION__ should be defined!).

    + + +

    GCC extensions not implemented yet

    + + +

    clang tries to be compatible with gcc as much as possible, but some gcc +extensions are not implemented yet:

    + +
      +
    • clang does not support __label__ +(bug 3429). This is +a relatively small feature, so it is likely to be implemented relatively +soon.
      • + +
    • clang does not support attributes on function pointers +(bug 2461). This is +a relatively important feature, so it is likely to be implemented relatively +soon.
      • + +
    • clang does not support #pragma weak +(bug 3679). Due to +the uses described in the bug, this is likely to be implemented at some +point, at least partially.
      • + +
    • clang does not support #pragma align +(bug 3811). This is a +relatively small feature, so it is likely to be implemented relatively +soon.
      • + +
    • clang does not support code generation for local variables pinned to +registers (bug 3933). +This is a relatively small feature, so it is likely to be implemented +relatively soon.
      • + +
    • clang does not support decimal floating point types (_Decimal32 and +friends) or fixed-point types (_Fract and friends); nobody has expressed +interest in these features yet, so it's hard to say when they will be +implemented.
      • + +
    • clang does not support nested functions; this is a complex feature which +is infrequently used, so it is unlikely to be implemented anytime soon.
      • + +
    • clang does not support global register variables, this is unlikely +to be implemented soon because it requires additional LLVM backend support. +
      • + +
    • clang does not support static initialization of flexible array +members. This appears to be a rarely used extension, but could be +implemented pending user demand.
      • + +
    • clang does not support __builtin_va_arg_pack/__builtin_va_arg_pack_len. +This is used rarely, but in some potentially interesting places, like the +glibc headers, so it may be implemented pending user demand. Note that +because clang pretends to be like GCC 4.2, and this extension was introduced +in 4.3, the glibc headers will not try to use this extension with clang at +the moment.
      • + +
    • clang does not support the gcc extension for forward-declaring function +parameters; this has not showed up in any real-world code yet, though, so it +might never be implemented.
      • + +
    + +

    This is not a complete list; if you find an unsupported extension +missing from this list, please send an e-mail to cfe-dev. This list +currently excludes C++; see C++ Language Features. +Also, this list does not include bugs in mostly-implemented features; please +see the +bug tracker for known existing bugs (FIXME: Is there a section for +bug-reporting guidelines somewhere?).

    + + +

    Intentionally unsupported GCC extensions

    + + +
      + +
    • clang does not support the gcc extension that allows variable-length arrays +in structures. This is for a few of reasons: one, it is tricky +to implement, two, the extension is completely undocumented, and three, the +extension appears to be rarely used.
      • + +
    • clang does not support duplicate definitions of a function where one is +inline. This complicates clients of the AST which normally can expect there is +at most one definition for each function. Source code using this feature should +be changed to define the inline and out-of-line definitions in separate +translation units.
      • + +
    • clang does not have an equivalent to gcc's "fold"; this means that +clang doesn't accept some constructs gcc might accept in contexts where a +constant expression is required, like "x-x" where x is a variable, or calls +to C library functions like strlen.
      • + +
    • clang does not support multiple alternative constraints in inline asm; this +is an extremely obscure feature which would be complicated to implement +correctly.
      • + +
    • clang does not support __builtin_apply and friends; this extension is +extremely obscure and difficult to implement reliably.
      • + +
    + + +

    Microsoft extensions

    + + +

    clang has some experimental support for extensions from +Microsoft Visual C++; to enable it, use the -fms-extensions command-line +option. This is the default for Windows targets. Note that the +support is incomplete; enabling Microsoft extensions will silently drop +certain constructs (including __declspec and Microsoft-style asm statements). +

    + +
  • clang does not support the Microsoft extension where anonymous +record members can be declared using user defined typedefs.
    • + +
  • clang supports the Microsoft "#pragma pack" feature for +controlling record layout. GCC also contains support for this feature, +however where MSVC and GCC are incompatible clang follows the MSVC +definition.
    • + + +

    Objective-C Language Features

    + + + + +

    Intentional Incompatibilities with GCC

    + + +

    No cast of super, no lvalue casts.

    + + + + +

    C++ Language Features

    + + +

    At this point, Clang C++ is not production-quality and is not recommended for use beyond experimentation. However, Clang C++ support +is under active development and is progressing rapidly. Please see the C++ Status page for details or +ask on the mailing list about how you can help.

    + +

    Note that released Clang compilers will refuse to even try to use clang to compile C++ code unless you pass the -ccc-clang-cxx option to the driver. To turn on Clang's C++ support, please pass that flag. Clang compilers built from the Subversion trunk enable C++ support by default, and do not require the -ccc-clang-cxx flag.

    + +

    Clang strives to strictly conform to the C++ standard. That means +it will reject invalid C++ code that another compiler may accept. If +Clang reports errors in your code, please check +the C++ +Compatibility page to see whether they are C++-conformance bugs +and how you can fix them.

    + + +

    Objective C++ Language Features

    + + +

    At this point, Clang C++ support is not generally useful (and therefore, +neither is Objective-C++). Please see the C++ section for +more information.

    + + +

    Target-Specific Features and Limitations

    + + + + +

    CPU Architectures Features and Limitations

    + + + +

    X86

    + +

    The support for X86 (both 32-bit and 64-bit) is considered stable +on Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested to +correctly compile large C and Objective-C codebases. (FIXME: Anything specific +we want to say here? Possibly mention some LLVM x86 limitations?) + + +

    ARM

    + +ARM support is mostly feature-complete, but still experimental; it hasn't +undergone significant testing. + + +

    Other platforms

    + +clang currently contains some support for PPC and Sparc; however, significant +pieces of code generation are still missing, and they haven't undergone +significant testing. + +

    clang contains some support for the embedded PIC16 processor +(FIXME: I haven't been keeping track of this; what should this say?). + +

    clang contains limited support for the MSP430 embedded processor, but both +the clang support and the LLVM backend support are highly experimental. + +

    Other platforms are completely unsupported at the moment. Adding the +minimal support needed for parsing and semantic analysis on a new platform +is quite easy; see lib/Basic/Targets.cpp in the clang source tree. This level +of support is also sufficient for conversion to LLVM IR for simple programs. +Proper support for conversion to LLVM IR requires adding code to +lib/CodeGen/CGCall.cpp at the moment; this is likely to change soon, though. +Generating assembly requires a suitable LLVM backend. + + +

    Operating System Features and Limitations

    + + + +

    Darwin (Mac OS/X)

    + + +

    No __thread support, 64-bit ObjC support requires SL tools.

    + +
    + + diff --git a/docs/main/index.html b/docs/main/index.html new file mode 100644 index 0000000000..d741b68a41 --- /dev/null +++ b/docs/main/index.html @@ -0,0 +1,4 @@ +'clang' C frontend documentation + +None yet, sorry :( + diff --git a/docs/main/libIndex.html b/docs/main/libIndex.html new file mode 100644 index 0000000000..e722ee14d4 --- /dev/null +++ b/docs/main/libIndex.html @@ -0,0 +1,267 @@ + + + The Index Library + + + + + + + + + +
    + +

    The Index Library

    + +

    Table of Contents

    + + +

    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 -emit-ast t1.c -o t1.ast
+$ clang -emit-ast 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>
+
    +

    + +
    + + + diff --git a/docs/main/tools/clang.pod b/docs/main/tools/clang.pod new file mode 100644 index 0000000000..42cf8fa2d7 --- /dev/null +++ b/docs/main/tools/clang.pod @@ -0,0 +1,518 @@ +=pod + +=head1 NAME + +clang - the Clang C and Objective-C compiler + +=head1 SYNOPSIS + +B [B<-c>|B<-S>|B<-E>] B<-std=>I B<-g> + [B<-O0>|B<-O1>|B<-O2>|B<-Os>|B<-O3>|B<-O4>] + B<-W>I B<-pedantic> + B<-I>I B<-L>I + B<-D>I + B<-f>I + B<-m>I + B<-o> I + I + +=head1 DESCRIPTION + +B is a C and Objective-C compiler which encompasses preprocessing, +parsing, optimization, code generation, assembly, and linking. Depending on +which high-level mode setting is passed, Clang will stop before doing a full +link. While Clang is highly integrated, it is important to understand the +stages of compilation, to understand how to invoke it. These stages are: + +=over + +=item B + +The B executable is actually a small driver which controls the overall +execution of other tools such as the compiler, assembler and linker. Typically +you do not need to interact with the driver, but you transparently use it to run +the other tools. + +=item B + +This stage handles tokenization of the input source file, macro expansion, +#include expansion and handling of other preprocessor directives. The output of +this stage is typically called a ".i" (for C) or ".mi" (for Objective-C) file. + +=item B + +This stage parses the input file, translating preprocessor tokens into a parse +tree. Once in the form of a parser tree, it applies semantic analysis to compute +types for expressions as well and determine whether the code is well formed. This +stage is responsible for generating most of the compiler warnings as well as +parse errors. The output of this stage is an "Abstract Syntax Tree" (AST). + +=item B + +This stage translates an AST into low-level intermediate code (known as "LLVM +IR") and ultimately to machine code (depending on the optimization level). This +phase is responsible for optimizing the generated code and handling +target-specfic code generation. The output of this stage is typically called a +".s" file or "assembly" file. + +=item B + +This stage runs the target assembler to translate the output of the compiler +into a target object file. The output of this stage is typically called a ".o" +file or "object" file. + +=item B + +This stage runs the target linker to merge multiple object files into an +executable or dynamic library. The output of this stage is typically called an +"a.out", ".dylib" or ".so" file. + +=back + +The Clang compiler supports a large number of options to control each of these +stages. In addition to compilation of code, Clang also supports other tools: + +B + +The Clang Static Analyzer is a tool that scans source code to try to find bugs +though code analysis. This tool uses many parts of Clang and is built into the +same driver. + + +=head1 OPTIONS + +=head2 Stage Selection Options + +=over + +=item B<-E> + +Run the preprocessor stage. + +=item B<-fsyntax-only> + +Run the preprocessor, parser and type checking stages. + +=item B<-S> + +Run the previous stages as well as LLVM generation and optimization stages and +target-specific code generation, producing an assembly file. + +=item B<-c> + +Run all of the above, plus the assembler, generating a target ".o" object file. + +=item B + +If no stage selection option is specified, all stages above are run, and the +linker is run to combine the results into an executable or shared library. + +=item B<--analyze> + +Run the Clang Static Analyzer. + +=back + + + +=head2 Language Selection and Mode Options + +=over + +=item B<-x> I + +Treat subsequent input files as having type I. + +=item B<-std>=I + +Specify the language standard to compile for. + +=item B<-ansi> + +Same as B<-std=c89>. + +=item B<-ObjC++> + +Treat source input files as Objective-C++ inputs. + +=item B<-ObjC> + +Treat source input files as Objective-C inputs. + +=item B<-trigraphs> + +Enable trigraphs. + +=item B<-ffreestanding> + +Indicate that the file should be compiled for a freestanding, not a hosted, +environment. + +=item B<-fno-builtin> + +Disable special handling and optimizations of builtin functions like strlen and +malloc. + +=item B<-fmath-errno> + +Indicate that math functions should be treated as updating errno. + +=item B<-fpascal-strings> + +Enable support for Pascal-style strings with "\pfoo". + +=item B<-fms-extensions> + +Enable support for Microsoft extensions. + +=item B<-fwritable-strings> + +Make all string literals default to writable. This disables uniquing of +strings and other optimizations. + +=item B<-flax-vector-conversions> + +Allow loose type checking rules for implicit vector conversions. + +=item B<-fblocks> + +Enable the "Blocks" language feature. + + +=item B<-fobjc-gc-only> + +Indicate that Objective-C code should be compiled in GC-only mode, which only +works when Objective-C Garbage Collection is enabled. + +=item B<-fobjc-gc> + +Indicate that Objective-C code should be compiled in hybrid-GC mode, which works +with both GC and non-GC mode. + +=back + + + +=head2 Target Selection Options + +Clang fully supports cross compilation as an inherent part of its design. +Depending on how your version of Clang is configured, it may have support for +a number of cross compilers, or may only support a native target. + +=over + +=item B<-arch> I + +Specify the architecture to build for. + +=item B<-mmacosx-version-min>=I + +When building for Mac OS/X, specify the minimum version supported by your +application. + +=item B<-miphoneos-version-min> + +When building for iPhone OS, specify the minimum version supported by your +application. + + +=item B<-march>=I + +Specify that Clang should generate code for a specific processor family member +and later. For example, if you specify -march=i486, the compiler is allowed to +generate instructions that are valid on i486 and later processors, but which +may not exist on earlier ones. + +=back + + +=head2 Code Generation Options + +=over + +=item B<-O0> B<-O1> B<-O2> B<-Os> B<-O3> B<-O4> + +Specify which optimization level to use. B<-O0> means "no optimization": this +level compiles the fastest and generates the most debuggable code. B<-O2> is a +moderate level of optimization which enables most optimizations. B<-Os> is like +B<-O2> with extra optimizations to reduce code size. B<-O3> is like B<-O2>, +except that it enables optimizations that take longer to perform or that may +generate larger code (in an attempt to make the program run faster). On +supported platforms, B<-O4> enables link-time optimization; object files are +stored in the LLVM bitcode file format and whole program optimization is done at +link time. B<-O1> is somewhere between B<-O0> and B<-O2>. + +=item B<-g> + +Generate debug information. Note that Clang debug information works best at +B<-O0>. At higher optimization levels, only line number information is +currently available. + +=item B<-fexceptions> + +Enable generation of unwind information, this allows exceptions to be thrown +through Clang compiled stack frames. This is on by default in x86-64. + +=item B<-ftrapv> + +Generate code to catch integer overflow errors. Signed integer overflow is +undefined in C, with this flag, extra code is generated to detect this and abort +when it happens. + + +=item B<-fvisibility> + +This flag sets the default visibility level. + +=item B<-fcommon> + +This flag specifies that variables without initializers get common linkage. It +can be disabled with B<-fno-common>. + +=item B<-flto> B<-emit-llvm> + +Generate output files in LLVM formats, suitable for link time optimization. When +used with B<-S> this generates LLVM intermediate language assembly files, +otherwise this generates LLVM bitcode format object files (which may be passed +to the linker depending on the stage selection options). + +=cut + +##=item B<-fnext-runtime> B<-fobjc-nonfragile-abi> B<-fgnu-runtime> +##These options specify which Objective-C runtime the code generator should +##target. FIXME: we don't want people poking these generally. + +=pod + +=back + + +=head2 Driver Options + +=over + +=item B<-###> + +Print the commands to run for this compilation. + +=item B<--help> + +Display available options. + +=item B<-Qunused-arguments> + +Don't emit warning for unused driver arguments. + +=item B<-Wa,>I + +Pass the comma separated arguments in I to the assembler. + +=item B<-Wl,>I + +Pass the comma separated arguments in I to the linker. + +=item B<-Wp,>I + +Pass the comma separated arguments in I to the preprocessor. + +=item B<-Xanalyzer> I + +Pass I to the static analyzer. + +=item B<-Xassembler> I + +Pass I to the assembler. + +=item B<-Xclang> I + +Pass I to the clang compiler. + +=item B<-Xlinker> I + +Pass I to the linker. + +=item B<-Xpreprocessor> I + +Pass I to the preprocessor. + +=item B<-o> I + +Write output to I. + +=item B<-print-file-name>=I + +Print the full library path of I. + +=item B<-print-libgcc-file-name> + +Print the library path for "libgcc.a". + +=item B<-print-prog-name>=I + +Print the full program path of I. + +=item B<-print-search-dirs> + +Print the paths used for finding libraries and programs. + +=item B<-save-temps> + +Save intermediate compilation results. + +=item B<-time> + +Time individual commands. + +=item B<-ftime-report> + +Print timing summary of each stage of compilation. + +=item B<-v> + +Show commands to run and use verbose output. + +=back + + +=head2 Diagnostics Options + +=over + +=item B<-fshow-column> +B<-fshow-source-location> +B<-fcaret-diagnostics> +B<-fdiagnostics-fixit-info> +B<-fdiagnostics-print-source-range-info> +B<-fprint-source-range-info> +B<-fdiagnostics-show-option> +B<-fmessage-length> + +These options control how Clang prints out information about diagnostics (errors +and warnings). Please see the Clang User's Manual for more information. + +=back + + +=head2 Preprocessor Options + +=over + +=item B<-D>I + +Adds an implicit #define into the predefines buffer which is read before the +source file is preprocessed. + +=item B<-U>I + +Adds an implicit #undef into the predefines buffer which is read before the +source file is preprocessed. + +=item B<-include> I + +Adds an implicit #include into the predefines buffer which is read before the +source file is preprocessed. + +=item B<-I>I + +Add the specified directory to the search path for include files. + +=item B<-F>I + +Add the specified directory to the search path for framework include files. + +=item B<-nostdinc> + +Do not search the standard system directories for include files. + +=item B<-nobuiltininc> + +Do not search clang's builtin directory for include files. + +=cut + +## TODO, but do we really want people using this stuff? +#=item B<-idirafter>I +#=item B<-iquote>I +#=item B<-isystem>I +#=item B<-iprefix>I +#=item B<-iwithprefix>I +#=item B<-iwithprefixbefore>I +#=item B<-isysroot> + +=pod + + +=back + + + +=cut + +### TODO someday. +#=head2 Warning Control Options +#=over +#=back +#=head2 Code Generation and Optimization Options +#=over +#=back +#=head2 Assembler Options +#=over +#=back +#=head2 Linker Options +#=over +#=back +#=head2 Static Analyzer Options +#=over +#=back + +=pod + + +=head1 ENVIRONMENT + +=over + +=item B, B, B + +These environment variables are checked, in order, for the location to +write temporary files used during the compilation process. + +=item B + +If this environment variable is present, it is treated as a delimited +list of paths to be added to the default system include path list. The +delimiter is the platform dependent delimitor, as used in the I +environment variable. + +Empty components in the environment variable are ignored. + +=item B, B, B, +B + +These environment variables specify additional paths, as for CPATH, +which are only used when processing the appropriate language. + +=item B + +If -mmacosx-version-min is unspecified, the default deployment target +is read from this environment variable. This option only affects darwin +targets. + +=back + +=head1 BUGS + +Clang currently does not have C++ support, and this manual page is incomplete. +To report bugs, please visit L. Most bug reports should +include preprocessed source files (use the B<-E> option) and the full output of +the compiler, along with information to reproduce. + +=head1 SEE ALSO + + as(1), ld(1) + +=head1 AUTHOR + +Maintained by the Clang / LLVM Team (L). + +=cut diff --git a/docs/main/tools/manpage.css b/docs/main/tools/manpage.css new file mode 100644 index 0000000000..c922564dc3 --- /dev/null +++ b/docs/main/tools/manpage.css @@ -0,0 +1,256 @@ +/* Based on http://www.perldoc.com/css/perldoc.css */ + +@import url("../llvm.css"); + +body { font-family: Arial,Helvetica; } + +blockquote { margin: 10pt; } + +h1, a { color: #336699; } + + +/*** Top menu style ****/ +.mmenuon { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ff6600; font-size: 10pt; +} +.mmenuoff { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: 10pt; +} +.cpyright { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: xx-small; +} +.cpyrightText { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #ffffff; font-size: xx-small; +} +.sections { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 11pt; +} +.dsections { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 12pt; +} +.slink { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #000000; font-size: 9pt; +} + +.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; } + +.maintitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 18pt; +} +.dblArrow { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: small; +} +.menuSec { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: small; +} + +.newstext { + font-family: Arial,Helvetica; font-size: small; +} + +.linkmenu { + font-family: Arial,Helvetica; color: #000000; font-weight: bold; + text-decoration: none; +} + +P { + font-family: Arial,Helvetica; +} + +PRE { + font-size: 10pt; +} +.quote { + font-family: Times; text-decoration: none; + color: #000000; font-size: 9pt; font-style: italic; +} +.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; } +.std { font-family: Arial,Helvetica; color: #000000; } +.meerkatTitle { + font-family: sans-serif; font-size: x-small; color: black; } + +.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black } +.meerkatCategory { + font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic; + color: brown; } +.meerkatChannel { + font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; } +.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; } + +.tocTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 10pt; +} + +.toc-item { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; text-decoration: underline; +} + +.perlVersion { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; text-decoration: none; +} + +.podTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #000000; +} + +.docTitle { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #000000; font-size: 10pt; +} +.dotDot { + font-family: Arial,Helvetica; font-weight: bold; + color: #000000; font-size: 9pt; +} + +.docSec { + font-family: Arial,Helvetica; font-weight: normal; + color: #333333; font-size: 9pt; +} +.docVersion { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 10pt; +} + +.docSecs-on { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #ff0000; font-size: 10pt; +} +.docSecs-off { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #333333; font-size: 10pt; +} + +h2 { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: medium; +} +h1 { + font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: large; +} + +DL { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; + color: #333333; font-size: 10pt; +} + +UL > LI > A { + font-family: Arial,Helvetica; font-weight: bold; + color: #336699; font-size: 10pt; +} + +.moduleInfo { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 11pt; +} + +.moduleInfoSec { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 10pt; +} + +.moduleInfoVal { + font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline; + color: #000000; font-size: 10pt; +} + +.cpanNavTitle { + font-family: Arial,Helvetica; font-weight: bold; + color: #ffffff; font-size: 10pt; +} +.cpanNavLetter { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #333333; font-size: 9pt; +} +.cpanCat { + font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; + color: #336699; font-size: 9pt; +} + +.bttndrkblue-bkgd-top { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif); +} +.bttndrkblue-bkgd-left { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif); +} +.bttndrkblue-bkgd { + padding-top: 0px; + padding-bottom: 0px; + margin-bottom: 0px; + margin-top: 0px; + background-repeat: no-repeat; + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif); + vertical-align: top; +} +.bttndrkblue-bkgd-right { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif); +} +.bttndrkblue-bkgd-bottom { + background-color: #225688; + background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif); +} +.bttndrkblue-text a { + color: #ffffff; + text-decoration: none; +} +a.bttndrkblue-text:hover { + color: #ffDD3C; + text-decoration: none; +} +.bg-ltblue { + background-color: #f0f5fa; +} + +.border-left-b { + background: #f0f5fa url(/i/corner-leftline.gif) repeat-y; +} + +.border-right-b { + background: #f0f5fa url(/i/corner-rightline.gif) repeat-y; +} + +.border-top-b { + background: #f0f5fa url(/i/corner-topline.gif) repeat-x; +} + +.border-bottom-b { + background: #f0f5fa url(/i/corner-botline.gif) repeat-x; +} + +.border-right-w { + background: #ffffff url(/i/corner-rightline.gif) repeat-y; +} + +.border-top-w { + background: #ffffff url(/i/corner-topline.gif) repeat-x; +} + +.border-bottom-w { + background: #ffffff url(/i/corner-botline.gif) repeat-x; +} + +.bg-white { + background-color: #ffffff; +} + +.border-left-w { + background: #ffffff url(/i/corner-leftline.gif) repeat-y; +} diff --git a/docs/tools/Makefile b/docs/tools/Makefile deleted file mode 100644 index 91bc447c08..0000000000 --- a/docs/tools/Makefile +++ /dev/null @@ -1,115 +0,0 @@ -##===- docs/tools/Makefile ---------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -ifdef BUILD_FOR_WEBSITE - -# FIXME: This was copied from the CommandGuide makefile. Figure out -# how to get this stuff on the website. - -# This special case is for keeping the CommandGuide on the LLVM web site -# up to date automatically as the documents are checked in. It must build -# the POD files to HTML only and keep them in the src directories. It must also -# build in an unconfigured tree, hence the ifdef. To use this, run -# make -s BUILD_FOR_WEBSITE=1 inside the cvs commit script. -SRC_DOC_DIR= -DST_HTML_DIR=html/ -DST_MAN_DIR=man/man1/ -DST_PS_DIR=ps/ -CLANG_VERSION := trunk - -# If we are in BUILD_FOR_WEBSITE mode, default to the all target. -all:: html man ps - -clean: - rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -# To create other directories, as needed, and timestamp their creation -%/.dir: - -mkdir $* > /dev/null - date > $@ - -else - -# Otherwise, if not in BUILD_FOR_WEBSITE mode, use the project info. -LEVEL := ../../../.. -include $(LEVEL)/Makefile.common - -CLANG_VERSION := $(shell cat $(PROJ_SRC_DIR)/../../VER) - -SRC_DOC_DIR=$(PROJ_SRC_DIR)/ -DST_HTML_DIR=$(PROJ_OBJ_DIR)/ -DST_MAN_DIR=$(PROJ_OBJ_DIR)/ -DST_PS_DIR=$(PROJ_OBJ_DIR)/ - -endif - - -POD := $(wildcard $(SRC_DOC_DIR)*.pod) -HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD)) -MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD)) -PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD)) - -ifdef ONLY_MAN_DOCS -INSTALL_TARGETS := install-man -else -INSTALL_TARGETS := install-html install-man install-ps -endif - -.SUFFIXES: -.SUFFIXES: .html .pod .1 .ps - -$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir - pod2html --css=manpage.css --htmlroot=. \ - --podpath=. --infile=$< --outfile=$@ --title=$* - -$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir - pod2man --release "clang $(CLANG_VERSION)" --center="Clang Tools Documentation" $< $@ - -$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir - groff -Tps -man $< > $@ - - -html: $(HTML) -man: $(MAN) -ps: $(PS) - -EXTRA_DIST := $(POD) - -clean-local:: - $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/clang -MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1 -PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps - -install-html:: $(HTML) - $(Echo) Installing HTML Clang Tools Documentation - $(Verb) $(MKDIR) $(HTML_DIR) - $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) - -install-man:: $(MAN) - $(Echo) Installing MAN Clang Tools Documentation - $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(MAN) $(MAN_DIR) - -install-ps:: $(PS) - $(Echo) Installing PS Clang Tools Documentation - $(Verb) $(MKDIR) $(PS_DIR) - $(Verb) $(DataInstall) $(PS) $(PS_DIR) - -install-local:: $(INSTALL_TARGETS) - -uninstall-local:: - $(Echo) Uninstalling Clang Tools Documentation - $(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR) - -printvars:: - $(Echo) "POD : " '$(POD)' - $(Echo) "HTML : " '$(HTML)' -- cgit v1.2.3-18-g5258