diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Block-ABI-Apple.txt | 78 | ||||
| -rw-r--r-- | docs/InternalsManual.html | 125 | ||||
| -rw-r--r-- | docs/LanguageExtensions.html | 200 | ||||
| -rw-r--r-- | docs/Makefile | 4 | ||||
| -rw-r--r-- | docs/PCHInternals.html | 8 | ||||
| -rw-r--r-- | docs/UsersManual.html | 79 | ||||
| -rw-r--r-- | docs/tools/clang.pod | 36 |
7 files changed, 416 insertions, 114 deletions
diff --git a/docs/Block-ABI-Apple.txt b/docs/Block-ABI-Apple.txt index dd12036..4a97aa9 100644 --- a/docs/Block-ABI-Apple.txt +++ b/docs/Block-ABI-Apple.txt @@ -67,19 +67,21 @@ 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_STRET = (1 << 29), // IFF BLOCK_HAS_SIGNATURE 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. +In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime - it had been 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): <unused> , error + case (0<<29): 10.6.ABI, no signature field available 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 signature field is not always populated. + 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. @@ -348,7 +350,7 @@ void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) { 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 }; + .captured_voidBlock=blockA )}; voidBlock.forwarding->captured_voidBlock = blockB; @@ -422,7 +424,9 @@ A __block variable that is also marked __attribute__((NSObject)) should have byr 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. +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. The call should be: + + _Block_object_dispose(&_block_byref_xxx, BLOCK_FIELD_IS_BYREF); 2.3.6 Nesting @@ -537,9 +541,9 @@ and within the compound statement: 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. +Within a block stack based C++ objects are copied into const copies using the copy constructor. It is an error if a stack based C++ object is used within a block if it does not have a 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: +As an example, suppose a C++ class FOO existed with a copy constructor. Within a code block a stack version of a FOO object is declared and used within a Block literal expression: { FOO foo; @@ -562,11 +566,11 @@ void __block_invoke_10(struct __block_literal_10 *_block) { } void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) { - comp_ctor(&dst->foo, &src->foo); + FOO_ctor(&dst->foo, &src->foo); } void __block_dispose_10(struct __block_literal_10 *src) { - comp_dtor(&src->foo); + FOO_dtor(&src->foo); } static struct __block_descriptor_10 { @@ -594,9 +598,33 @@ and the code would be: } -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. +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. For example, + + __block FOO blockStorageFoo; + +requires the normal constructor for the embedded blockStorageFoo object + + FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo); + +and at scope termination the destructor: + + FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo); + +Note that the forwarding indirection is NOT used. + +The compiler would need to generate (if used from a block literal) the following copy/dispose helpers: + +void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) { + FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo); +} + +void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) { + FOO_dtor(&src->blockStorageFoo); +} + +for the appropriately named constructor and destructor for the class/struct FOO. -To support member variable and function access the compiler will synthesize a const pointer to a block version of the this pointer. +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 @@ -640,31 +668,3 @@ void _Block_object_assign(void *destAddr, const void *object, const int flags); */ 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/InternalsManual.html b/docs/InternalsManual.html index 6df26db..813015e 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -25,6 +25,7 @@ td { <li><a href="#Diagnostics">The Diagnostics Subsystem</a></li> <li><a href="#SourceLocation">The SourceLocation and SourceManager classes</a></li> + <li><a href="#SourceRange">SourceRange and CharSourceRange</a></li> </ul> </li> <li><a href="#libdriver">The Driver Library</a> @@ -68,6 +69,11 @@ td { </ul> </li> <li><a href="libIndex.html">The Index Library</a></li> +<li><a href="#Howtos">Howto guides</a> + <ul> + <li><a href="#AddingAttributes">How to add an attribute</a></li> + </ul> +</li> </ul> @@ -145,15 +151,14 @@ diagnostic :).</p> pieces, this section describes them and talks about best practices when adding a new diagnostic.</p> -<!-- ============================== --> -<h4>The Diagnostic*Kinds.def files</h4> -<!-- ============================== --> +<!-- ============================= --> +<h4>The Diagnostic*Kinds.td files</h4> +<!-- ============================= --> <p>Diagnostics are created by adding an entry to one of the <tt> -clang/Basic/Diagnostic*Kinds.def</tt> 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.</p> +clang/Basic/Diagnostic*Kinds.td</tt> files, depending on what library will +be using it. From this file, tblgen generates the unique ID of the diagnostic, +the severity of the diagnostic and the English translation + format string.</p> <p>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 @@ -237,7 +242,7 @@ are some simple format strings:</p> <ul> <li>Keep the string short. It should ideally fit in the 80 column limit of the - <tt>DiagnosticKinds.def</tt> file. This avoids the diagnostic wrapping when + <tt>DiagnosticKinds.td</tt> file. This avoids the diagnostic wrapping when printed, and forces you to think about the important point you are conveying with the diagnostic.</li> <li>Take advantage of location information. The user will be able to see the @@ -252,7 +257,7 @@ are some simple format strings:</p> <p>Diagnostics should never take random English strings as arguments: you shouldn't use <tt>"you have a problem with %0"</tt> and pass in things like <tt>"your argument"</tt> or <tt>"your return value"</tt> as arguments. Doing -this prevents <a href="translation">translating</a> the Clang diagnostics to +this prevents <a href="#translation">translating</a> 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 (<tt>/=</tt>). Note @@ -367,10 +372,10 @@ of repetitive diagnostics and/or have an idea for a useful formatter, please bring it up on the cfe-dev mailing list.</p> <!-- ===================================================== --> -<h4><a name="#producingdiag">Producing the Diagnostic</a></h4> +<h4 id="producingdiag">Producing the Diagnostic</h4> <!-- ===================================================== --> -<p>Now that you've created the diagnostic in the DiagnosticKinds.def file, you +<p>Now that you've created the diagnostic in the DiagnosticKinds.td 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 @@ -388,7 +393,7 @@ it.</p> <p>This shows that use of the Diag method: they take a location (a <a href="#SourceLocation">SourceLocation</a> object) and a diagnostic enum value -(which matches the name from DiagnosticKinds.def). If the diagnostic takes +(which matches the name from DiagnosticKinds.td). 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 <tt>int</tt> and @@ -545,6 +550,30 @@ 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.</p> + +<!-- ======================================================================= --> +<h3 id="SourceRange">SourceRange and CharSourceRange</h3> +<!-- ======================================================================= --> +<!-- mostly taken from + http://lists.cs.uiuc.edu/pipermail/cfe-dev/2010-August/010595.html --> + +<p>Clang represents most source ranges by [first, last], where first and last +each point to the beginning of their respective tokens. For example +consider the SourceRange of the following statement:</p> +<pre> +x = foo + bar; +^first ^last +</pre> + +<p>To map from this representation to a character-based +representation, the 'last' location needs to be adjusted to point to +(or past) the end of that token with either +<code>Lexer::MeasureTokenLength()</code> or +<code>Lexer::getLocForEndOfToken()</code>. For the rare cases +where character-level source ranges information is needed we use +the <code>CharSourceRange</code> class.</p> + + <!-- ======================================================================= --> <h2 id="libdriver">The Driver Library</h2> <!-- ======================================================================= --> @@ -1682,10 +1711,82 @@ interacts with constant evaluation:</p> floating-point literal.</li> <li><b><tt>__builtin_abs,copysign,..</tt></b>: These are constant folded as general constant expressions.</li> +<li><b><tt>__builtin_strlen</tt></b> and <b><tt>strlen</tt></b>: These are constant folded as integer constant expressions if the argument is a string literal.</li> </ul> +<!-- ======================================================================= --> +<h2 id="Howtos">How to change Clang</h2> +<!-- ======================================================================= --> + +<!-- ======================================================================= --> +<h3 id="AddingAttributes">How to add an attribute</h3> +<!-- ======================================================================= --> +<p>To add an attribute, you'll have to add it to the list of attributes, add it +to the parsing phase, and look for it in the AST scan. +<a href="http://llvm.org/viewvc/llvm-project?view=rev&revision=124217">r124217</a> +has a good example of adding a warning attribute.</p> + +<p>(Beware that this hasn't been reviewed/fixed by the people who designed the +attributes system yet.)</p> + +<h4><a +href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup">include/clang/Basic/Attr.td</a></h4> + +<p>Each attribute gets a <tt>def</tt> inheriting from <tt>Attr</tt> or one of +its subclasses. <tt>InheritableAttr</tt> means that the attribute also applies +to subsequent declarations of the same name.</p> + +<p><tt>Spellings</tt> lists the strings that can appear in +<tt>__attribute__((here))</tt> or <tt>[[here]]</tt>. All such strings +will be synonymous. If you want to allow the <tt>[[]]</tt> C++0x +syntax, you have to define a list of <tt>Namespaces</tt>, which will +let users write <tt>[[namespace:spelling]]</tt>. Using the empty +string for a namespace will allow users to write just the spelling +with no "<tt>:</tt>".</p> + +<p><tt>Subjects</tt> restricts what kinds of AST node to which this attribute +can appertain (roughly, attach).</p> + +<p><tt>Args</tt> names the arguments the attribute takes, in order. If +<tt>Args</tt> is <tt>[StringArgument<"Arg1">, IntArgument<"Arg2">]</tt> +then <tt>__attribute__((myattribute("Hello", 3)))</tt> will be a valid use.</p> + +<h4>Boilerplate</h4> + +<p>Add an element to the <tt>AttributeList::Kind</tt> enum in <a +href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/AttributeList.h?view=markup">include/clang/Sema/AttributeList.h</a> +named <tt>AT_lower_with_underscores</tt>. That is, a CamelCased +<tt>AttributeName</tt> in <tt>Attr.td</tt> name should become +<tt>AT_attribute_name</tt>.</p> + +<p>Add a case to the <tt>StringSwitch</tt> in <tt>AttributeList::getKind()</tt> +in <a +href="http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/AttributeList.cpp?view=markup">lib/Sema/AttributeList.cpp</a> +for each spelling of your attribute. Less common attributes should come toward +the end of that list.</p> + +<p>Write a new <tt>HandleYourAttr()</tt> function in <a +href="http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup">lib/Sema/SemaDeclAttr.cpp</a>, +and add a case to the switch in <tt>ProcessNonInheritableDeclAttr()</tt> or +<tt>ProcessInheritableDeclAttr()</tt> forwarding to it.</p> + +<p>If your attribute causes extra warnings to fire, define a <tt>DiagGroup</tt> +in <a +href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticGroups.td?view=markup">include/clang/Basic/DiagnosticGroups.td</a> +named after the attribute's <tt>Spelling</tt> with "_"s replaced by "-"s. If +you're only defining one diagnostic, you can skip <tt>DiagnosticGroups.td</tt> +and use <tt>InGroup<DiagGroup<"your-attribute">></tt> directly in <a +href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticSemaKinds.td?view=markup">DiagnosticSemaKinds.td</a></p> + +<h4>The meat of your attribute</h4> + +<p>Find an appropriate place in Clang to do whatever your attribute needs to do. +Check for the attribute's presence using <tt>Decl::getAttr<YourAttr>()</tt>.</p> + +<p>Update the <a href="LanguageExtensions.html">Clang Language Extensions</a> +document to describe your new attribute.</p> </div> </body> diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html index 75a4608..8f412c6 100644 --- a/docs/LanguageExtensions.html +++ b/docs/LanguageExtensions.html @@ -23,6 +23,8 @@ td { <li><a href="#has_include">Include File Checking Macros</a></li> <li><a href="#builtinmacros">Builtin Macros</a></li> <li><a href="#vectors">Vectors and Extended Vectors</a></li> +<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li> +<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li> <li><a href="#checking_language_features">Checks for Standard Language Features</a></li> <ul> <li><a href="#cxx_exceptions">C++ exceptions</a></li> @@ -32,23 +34,27 @@ td { <ul> <li><a href="#cxx_attributes">C++0x attributes</a></li> <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li> + <li><a href="#cxx_default_function_template_args">C++0x default template arguments in function templates</a></li> <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li> - <li><a href="#cxx_concepts">C++ TR concepts</a></li> <li><a href="#cxx_lambdas">C++0x lambdas</a></li> <li><a href="#cxx_nullptr">C++0x nullptr</a></li> <li><a href="#cxx_rvalue_references">C++0x rvalue references</a></li> + <li><a href="#cxx_reference_qualified_functions">C++0x reference-qualified functions</a></li> <li><a href="#cxx_static_assert">C++0x <tt>static_assert()</tt></a></li> <li><a href="#cxx_auto_type">C++0x type inference</a></li> <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li> <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li> + <li><a href="#cxx_strong_enums">C++0x strongly-typed enumerations</a></li> + <li><a href="#cxx_trailing_return">C++0x trailing return type</a></li> </ul> +<li><a href="#checking_type_traits">Checks for Type Traits</a></li> <li><a href="#blocks">Blocks</a></li> <li><a href="#overloading-in-c">Function Overloading in C</a></li> <li><a href="#builtins">Builtin Functions</a> <ul> <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li> <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li> - </ul> + </ul> </li> <li><a href="#targetspecific">Target-Specific Extensions</a> <ul> @@ -133,6 +139,30 @@ can be used like this:</p> <p>The feature tag is described along with the language feature below.</p> <!-- ======================================================================= --> +<h3 id="__has_attribute">__has_attribute</h3> +<!-- ======================================================================= --> + +<p>This function-like macro takes a single identifier argument that is the name +of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It +can be used like this:</p> + +<blockquote> +<pre> +#ifndef __has_attribute // Optional of course. + #define __has_attribute(x) 0 // Compatibility with non-clang compilers. +#endif + +... +#if __has_attribute(always_inline) +#define ALWAYS_INLINE __attribute__((always_inline)) +#else +#define ALWAYS_INLINE +#endif +... +</pre> +</blockquote> + +<!-- ======================================================================= --> <h2 id="has_include">Include File Checking Macros</h2> <!-- ======================================================================= --> @@ -259,6 +289,7 @@ float4 foo(float2 a, float2 b) { c.yw = b; return c; } +</pre> </blockquote> <p>Query for this feature with __has_feature(attribute_ext_vector_type).</p> @@ -266,6 +297,53 @@ float4 foo(float2 a, float2 b) { <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p> <!-- ======================================================================= --> +<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2> +<!-- ======================================================================= --> + +<p>An optional string message can be added to the <tt>deprecated</tt> +and <tt>unavailable</tt> attributes. For example:</p> + +<blockquote> +<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre> +</blockquote> + +<p>If the deprecated or unavailable declaration is used, the message +will be incorporated into the appropriate diagnostic:</p> + +<blockquote> +<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations] + explode(); + ^</pre> +</blockquote> + +<p>Query for this feature +with <tt>__has_feature(attribute_deprecated_with_message)</tt> +and <tt>__has_feature(attribute_unavailable_with_message)</tt>.</p> + +<!-- ======================================================================= --> +<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2> +<!-- ======================================================================= --> + +<p>Clang allows attributes to be written on individual enumerators. +This allows enumerators to be deprecated, made unavailable, etc. The +attribute must appear after the enumerator name and before any +initializer, like so:</p> + +<blockquote> +<pre>enum OperationMode { + OM_Invalid, + OM_Normal, + OM_Terrified __attribute__((deprecated)), + OM_AbortOnError __attribute__((deprecated)) = 4 +};</pre> +</blockquote> + +<p>Attributes on the <tt>enum</tt> declaration do not apply to +individual enumerators.</p> + +<p>Query for this feature with <tt>__has_feature(enumerator_attributes)</tt>.</p> + +<!-- ======================================================================= --> <h2 id="checking_language_features">Checks for Standard Language Features</h2> <!-- ======================================================================= --> @@ -304,16 +382,15 @@ not yet implemented will be noted.</p> <p>Use <tt>__has_feature(cxx_attributes)</tt> to determine if support for attribute parsing with C++0x's square bracket notation is enabled.</p> +<h3 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h3> + +<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> to determine if support for default template arguments in function templates is enabled.</p> + <h3 id="cxx_deleted_functions">C++0x deleted functions</tt></h3> <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> to determine if support for deleted function definitions (with <tt>= delete</tt>) is enabled.</p> -<h3 id="cxx_concepts">C++ TR concepts</h3> - -<p>Use <tt>__has_feature(cxx_concepts)</tt> to determine if support for -concepts is enabled. clang does not currently implement this feature.</p> - <h3 id="cxx_lambdas">C++0x lambdas</h3> <p>Use <tt>__has_feature(cxx_lambdas)</tt> to determine if support for @@ -325,11 +402,13 @@ lambdas is enabled. clang does not currently implement this feature.</p> <tt>nullptr</tt> is enabled. clang does not yet fully implement this feature.</p> +<h3 id="cxx_reference_qualified_functions">C++0x reference-qualified functions</h3> +<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> to determine if support for reference-qualified functions (e.g., member functions with <code>&</code> or <code>&&</code> applied to <code>*this</code>) is enabled.</p> + <h3 id="cxx_rvalue_references">C++0x rvalue references</tt></h3> <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> to determine if support for -rvalue references is enabled. clang does not yet fully implement this -feature.</p> +rvalue references is enabled. </p> <h3 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h3> @@ -340,19 +419,69 @@ compile-time assertions using <tt>static_assert</tt> is enabled.</p> <p>Use <tt>__has_feature(cxx_auto_type)</tt> to determine C++0x type inference is supported using the <tt>auto</tt> specifier. If this is disabled, -<tt>auto</tt> will instead be a storage class specifier, as in C or C++98.</p> +<tt>auto</tt> will instead be a storage class specifier, as in C or C++98. +Clang does not currently implement this feature.</p> <h3 id="cxx_variadic_templates">C++0x variadic templates</h3> <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> 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.</p> +for variadic templates is enabled.</p> <h3 id="cxx_inline_namespaces">C++0x inline namespaces</h3> <p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> to determine if support for inline namespaces is enabled.</p> +<h3 id="cxx_trailing_return">C++0x trailing return type</h3> + +<p>Use <tt>__has_feature(cxx_trailing_return)</tt> to determine if support for +the alternate function declaration syntax with trailing return type is enabled.</p> + +<h3 id="cxx_strong_enums">C++0x strongly typed enumerations</h3> + +<p>Use <tt>__has_feature(cxx_strong_enums)</tt> to determine if support for +strongly typed, scoped enumerations is enabled.</p> + +<!-- ======================================================================= --> +<h2 id="checking_type_traits">Checks for Type Traits</h2> +<!-- ======================================================================= --> + +<p>Clang supports the <a hef="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the <a href="http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>. For each supported type trait <code>__X</code>, <code>__has_feature(X)</code> indicates the presence of the type trait. For example: +<blockquote> +<pre> +#if __has_feature(is_convertible_to) +template<typename From, typename To> +struct is_convertible_to { + static const bool value = __is_convertible_to(From, To); +}; +#else +// Emulate type trait +#endif +</pre> +</blockquote> + +<p>The following type traits are supported by Clang:</p> +<ul> + <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li> + <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li> + <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li> + <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li> + <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li> + <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li> + <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li> + <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li> + <li><code>__is_abstract</code> (GNU, Microsoft)</li> + <li><code>__is_base_of</code> (GNU, Microsoft)</li> + <li><code>__is_class</code> (GNU, Microsoft)</li> + <li><code>__is_convertible_to</code> (Microsoft)</li> + <li><code>__is_empty</code> (GNU, Microsoft)</li> + <li><code>__is_enum</code> (GNU, Microsoft)</li> + <li><code>__is_pod</code> (GNU, Microsoft)</li> + <li><code>__is_polymorphic</code> (GNU, Microsoft)</li> + <li><code>__is_union</code> (GNU, Microsoft)</li> + <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li> +</ul> + <!-- ======================================================================= --> <h2 id="blocks">Blocks</h2> <!-- ======================================================================= --> @@ -445,7 +574,7 @@ void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me their names mangled according to the same rules as C++ function names. For example, the three <tt>tgsin</tt> functions in our motivating example get the mangled names <tt>_Z5tgsinf</tt>, -<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two +<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two caveats to this use of name mangling:</p> <ul> @@ -660,6 +789,51 @@ placed at the end of function prototypes:</p> <p>Query for this feature with __has_feature(attribute_analyzer_noreturn).</p> +<h4 id="attr_retain_release">Objective-C retaining behavior attributes</h4> + +<p>In Objective-C, functions and methods are generally assumed to take +and return objects with +0 retain counts, with some exceptions for +special methods like <tt>+alloc</tt> and <tt>init</tt>. However, +there are exceptions, and so Clang provides attributes to allow these +exceptions to be documented, which helps the analyzer find leaks (and +ignore non-leaks).</p> + +<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>, +<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>, +and <tt>cf_returns_not_retained</tt> attributes can be placed on +methods and functions that return Objective-C or CoreFoundation +objects. They are commonly placed at the end of a function prototype +or method declaration:</p> + +<pre> + id foo() <b>__attribute__((ns_returns_retained))</b>; + + - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>; +</pre> + +<p>The <tt>*_returns_retained</tt> attributes specify that the +returned object has a +1 retain count. +The <tt>*_returns_not_retained</tt> attributes specify that the return +object has a +0 retain count, even if the normal convention for its +selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the +returned object is +0, but is guaranteed to live at least as long as the +next flush of an autorelease pool.</p> + +<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt> +attributes can be placed on an parameter declaration; they specify +that the argument is expected to have a +1 retain count, which will be +balanced in some way by the function or method. +The <tt>ns_consumes_self</tt> attribute can only be placed on an +Objective-C method; it specifies that the method expects +its <tt>self</tt> parameter to have a +1 retain count, which it will +balance in some way.</p> + +<pre> + void <b>foo(__attribute__((ns_consumed))</b> NSString *string); + + - (void) bar <b>__attribute__((ns_consumes_self))</b>; + - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x; +</pre> </div> </body> diff --git a/docs/Makefile b/docs/Makefile index 053b263..f82d820 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -59,7 +59,7 @@ $(PROJ_OBJ_DIR)/html.tar.gz: $(HTML) $(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 + $(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar install-doxygen: doxygen $(Echo) Installing doxygen documentation @@ -82,7 +82,7 @@ $(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) $(GZIPBIN) $(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 diff --git a/docs/PCHInternals.html b/docs/PCHInternals.html index 109d5ed..d46ae5c 100644 --- a/docs/PCHInternals.html +++ b/docs/PCHInternals.html @@ -391,23 +391,23 @@ 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 +subexpressions of an expression are stored, in reverse order, prior to the expression that owns those expression, using a form of <a href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">Reverse Polish Notation</a>. For example, an expression <code>3 - 4 + 5</code> would be represented as follows:</p> <table border="1"> - <tr><td><code>IntegerLiteral(3)</code></td></tr> + <tr><td><code>IntegerLiteral(5)</code></td></tr> <tr><td><code>IntegerLiteral(4)</code></td></tr> + <tr><td><code>IntegerLiteral(3)</code></td></tr> <tr><td><code>BinaryOperator(-)</code></td></tr> - <tr><td><code>IntegerLiteral(5)</code></td></tr> <tr><td><code>BinaryOperator(+)</code></td></tr> <tr><td>STOP</td></tr> </table> <p>When reading this representation, Clang evaluates each expression -record it encounters, builds the appropriate abstract synax tree node, +record it encounters, builds the appropriate abstract syntax tree node, and then pushes that expression on to a stack. When a record contains <i>N</i> subexpressions--<code>BinaryOperator</code> has two of them--those expressions are popped from the top of the stack. The special STOP diff --git a/docs/UsersManual.html b/docs/UsersManual.html index 7524161..82c4fa2 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -248,32 +248,29 @@ when this is enabled, Clang will print something like:</p> ^ // </pre> - -<p>When this is disabled, Clang will just print:</p> - -<pre> - <b><font color="black">test.c:28:8: <font color="magenta">warning</font>: extra tokens at end of #endif directive [-Wextra-tokens]</font></b> - #endif bad - <font color="green">^</font> - <font color="green">//</font> -</pre> - </dd> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <dt id="opt_fcolor_diagnostics"><b>-f[no-]color-diagnostics</b>: </dt> <dd>This option, which defaults to on when a color-capable terminal is detected, controls whether or not Clang prints diagnostics in color. When this option is enabled, Clang will use colors to highlight specific parts of the diagnostic, e.g., - + <pre> + <b><font color="black">test.c:28:8: <font color="magenta">warning</font>: extra tokens at end of #endif directive [-Wextra-tokens]</font></b> + #endif bad + <font color="green">^</font> + <font color="green">//</font> +</pre> + +<p>When this is disabled, Clang will just print:</p> + <pre> -<test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] -#endif bad - ^ - // + test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens] + #endif bad + ^ + // </pre> -</dd>' +</dd> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <dt id="opt_fdiagnostics-show-option"><b>-f[no-]diagnostics-show-option</b>: Enable <tt>[-Woption]</tt> information in diagnostic line.</dt> @@ -565,7 +562,7 @@ example code will tell Clang or GCC to ignore the -Wall warnings:</p> #pragma GCC diagnostic ignored "-Wall" </pre> -<p>In addition to all of the functionality of provided by GCC's pragma, Clang +<p>In addition to all of the functionality 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.</p> @@ -604,7 +601,7 @@ by the user via changes to the source code. This can be done in two ways: attributes (e.g., <tt>__attribute__((nonnull)))</tt>) that can either suppress static analyzer warnings or teach the analyzer about code invariants which enable it to find more bugs. While many of these attributes are standard GCC -attributes, additional ones have added to Clang to specifically support the +attributes, additional ones have been added to Clang to specifically support the static analyzer. Detailed information on these annotations can be found in the <a href="http://clang-analyzer.llvm.org/annotations.html">analyzer's documentation</a>.</li> @@ -623,7 +620,7 @@ selectively exclude code the analyzer examines. Here is an example: In general, this usage is discouraged. Instead, we prefer that users file bugs against the analyzer when it flags false positives. There is also active discussion of allowing users in the future to selectively silence specific -analyzer warnings (some which can already be done using <a +analyzer warnings (some of which can already be done using <a href="analyzer_annotations">annotations</a>).</li> </ul> @@ -642,7 +639,7 @@ 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 +headers vary between compilers, precompiled headers have been shown to be highly effective at speeding up program compilation on systems with very large system headers (e.g., Mac OS/X).</p> @@ -742,11 +739,11 @@ likely to affect PCH files that reference a large number of headers.</p> on runtime code generation to check for undefined behavior.</dt> <dd>This option, which defaults to off, controls whether or not Clang -adds runtime checks for undefined runtime behavior. If the check fails, +adds runtime checks for undefined runtime behavior. If a check fails, <tt>__builtin_trap()</tt> is used to indicate failure. The checks are: <p> -<li>Subscripting where the static type of one operand is variable +<li>Subscripting where the static type of one operand is a variable which is decayed from an array type and the other operand is greater than the size of the array or less than zero.</li> <li>Shift operators where the amount shifted is greater or equal to the @@ -761,7 +758,7 @@ The checks are: <dt id="opt_fno-assume-sane-operator-new"><b>-fno-assume-sane-operator-new</b>: Don't assume that the C++'s new operator is sane.</dt> <dd>This option tells the compiler to do not assume that C++'s global new -operator will always return a pointer that do not +operator will always return a pointer that does not alias any other pointer when the function returns.</dd> <!-- ======================================================================= --> @@ -828,10 +825,6 @@ c94 mode (FIXME: And __STDC_VERSION__ should be defined!).</p> extensions are not implemented yet:</p> <ul> -<li>clang does not support __label__ -(<a href="http://llvm.org/bugs/show_bug.cgi?id=3429">bug 3429</a>). This is -a relatively small feature, so it is likely to be implemented relatively -soon.</li> <li>clang does not support #pragma weak (<a href="http://llvm.org/bugs/show_bug.cgi?id=3679">bug 3679</a>). Due to @@ -887,9 +880,11 @@ bug-reporting guidelines somewhere?).</p> <ul> <li>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 +in structures. This is for a few reasons: one, it is tricky to implement, two, the extension is completely undocumented, and three, the -extension appears to be rarely used.</li> +extension appears to be rarely used. Note that clang <em>does</em> support +flexible array members (arrays with a zero or unspecified size at the end of +a structure).</li> <li>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 @@ -922,6 +917,12 @@ support is incomplete; enabling Microsoft extensions will silently drop certain constructs (including __declspec and Microsoft-style asm statements). </p> +<li>clang allows setting _MSC_VER with -fmsc-version=. It defaults to 1300 which +is the same as Visual C/C++ 2003. Any number is supported and can greatly affect +what Windows SDK and c++stdlib headers clang can compile. This option will be +removed when clang supports the full set of MS extensions required for these +headers.</li> + <li>clang does not support the Microsoft extension where anonymous record members can be declared using user defined typedefs.</li> @@ -942,16 +943,19 @@ definition.</li> <!-- ======================== --> <h4 id="target_arch_x86">X86</h4> <!-- ======================== --> -<p>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?) + +<p>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 many large C, C++, Objective-C, and Objective-C++ codebases.</p> <!-- ======================== --> <h4 id="target_arch_arm">ARM</h4> <!-- ======================== --> -ARM support is mostly feature-complete, but still experimental; it hasn't -undergone significant testing. + +<p>The support for ARM (specifically ARMv6 and ARMv7) is considered stable on +Darwin (iOS): it has been tested to correctly compile many large C, C++, +Objective-C, and Objective-C++ codebases. Clang only supports a limited number +of ARM architectures. It does not yet fully support ARMv5, for example.</p> <!-- ======================== --> <h4 id="target_arch_other">Other platforms</h4> @@ -960,9 +964,6 @@ 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. -<p>clang contains some support for the embedded PIC16 processor -(FIXME: I haven't been keeping track of this; what should this say?). - <p>clang contains limited support for the MSP430 embedded processor, but both the clang support and the LLVM backend support are highly experimental. diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod index 032efcf..9f7a448 100644 --- a/docs/tools/clang.pod +++ b/docs/tools/clang.pod @@ -2,7 +2,7 @@ =head1 NAME -clang - the Clang C and Objective-C compiler +clang - the Clang C, C++, and Objective-C compiler =head1 SYNOPSIS @@ -14,11 +14,12 @@ B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g> B<-f>I<feature-option...> B<-m>I<machine-option...> B<-o> I<output-file> + B<-stdlib=>I<library> I<input-filenames> =head1 DESCRIPTION -B<clang> is a C and Objective-C compiler which encompasses preprocessing, +B<clang> is a C, 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 @@ -37,7 +38,8 @@ the other tools. 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. +this stage is typically called a ".i" (for C), ".ii" (for C++), ".mi" (for +Objective-C) , or ".mii" (for Objective-C++) file. =item B<Parsing and Semantic Analysis> @@ -78,7 +80,7 @@ stages. In addition to compilation of code, Clang also supports other tools: B<Clang Static Analyzer> 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 +through code analysis. This tool uses many parts of Clang and is built into the same driver. @@ -130,6 +132,11 @@ Treat subsequent input files as having type I<language>. Specify the language standard to compile for. +=item B<-stdlib>=I<language> + +Specify the C++ standard library to use; supported options are libstdc++ and +libc++. + =item B<-ansi> Same as B<-std=c89>. @@ -168,6 +175,10 @@ Enable support for Pascal-style strings with "\pfoo". Enable support for Microsoft extensions. +=item B<-fmsc-version=> + +Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise. + =item B<-fborland-extensions> Enable support for Borland extensions. @@ -185,7 +196,6 @@ Allow loose type checking rules for implicit vector conversions. Enable the "Blocks" language feature. - =item B<-fobjc-gc-only> Indicate that Objective-C code should be compiled in GC-only mode, which only @@ -196,6 +206,22 @@ works when Objective-C Garbage Collection is enabled. Indicate that Objective-C code should be compiled in hybrid-GC mode, which works with both GC and non-GC mode. +=item B<-fobjc-abi-version>=I<version> + +Select the Objective-C ABI version to use. Available versions are 1 (legacy +"fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2). + +=item B<-fobjc-nonfragile-abi-version>=I<version> + +Select the Objective-C non-fragile ABI version to use by default. This will only +be used as the Objective-C ABI when the non-fragile ABI is enabled (either via +-fobjc-nonfragile-abi, or because it is the platform default). + +=item B<-fobjc-nonfragile-abi> + +Enable use of the Objective-C non-fragile ABI. On platforms for which this is +the default ABI, it can be disabled with B<-fno-objc-nonfragile-abi>. + =back |
