diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AddressSanitizer.html | 139 | ||||
| -rw-r--r-- | docs/AnalyzerRegions.html | 6 | ||||
| -rw-r--r-- | docs/AutomaticReferenceCounting.html | 387 | ||||
| -rw-r--r-- | docs/Block-ABI-Apple.txt | 1 | ||||
| -rw-r--r-- | docs/DriverInternals.html | 26 | ||||
| -rw-r--r-- | docs/InternalsManual.html | 64 | ||||
| -rw-r--r-- | docs/LanguageExtensions.html | 660 | ||||
| -rw-r--r-- | docs/ObjectiveCLiterals.html | 314 | ||||
| -rw-r--r-- | docs/PCHInternals.html | 8 | ||||
| -rw-r--r-- | docs/PTHInternals.html | 6 | ||||
| -rw-r--r-- | docs/ReleaseNotes.html | 193 | ||||
| -rw-r--r-- | docs/UsersManual.html | 89 | ||||
| -rw-r--r-- | docs/doxygen.cfg.in | 2 | ||||
| -rw-r--r-- | docs/tools/clang.pod | 2 |
14 files changed, 1623 insertions, 274 deletions
diff --git a/docs/AddressSanitizer.html b/docs/AddressSanitizer.html new file mode 100644 index 0000000..c1dc91b --- /dev/null +++ b/docs/AddressSanitizer.html @@ -0,0 +1,139 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> +<html> +<head> + <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + <title>AddressSanitizer, a fast memory error detector</title> + <link type="text/css" rel="stylesheet" href="../menu.css"> + <link type="text/css" rel="stylesheet" href="../content.css"> + <style type="text/css"> + td { + vertical-align: top; + } + </style> +</head> +<body> + +<!--#include virtual="../menu.html.incl"--> + +<div id="content"> + +<h1>AddressSanitizer</h1> +<ul> + <li> <a href="intro">Introduction</a> + <li> <a href="howtobuild">How to Build</a> + <li> <a href="usage">Usage</a> + <ul><li> <a href="has_feature">__has_feature(address_sanitizer)</a></ul> + <li> <a href="platforms">Supported Platforms</a> + <li> <a href="limitations">Limitations</a> + <li> <a href="status">Current Status</a> + <li> <a href="moreinfo">More Information</a> +</ul> + +<h2 id="intro">Introduction</h2> +AddressSanitizer is a fast memory error detector. +It consists of a compiler instrumentation module and a run-time library. +The tool can detect the following types of bugs: +<ul> <li> Out-of-bounds accesses to heap, stack and globals + <li> Use-after-free + <li> Use-after-return (to some extent) + <li> Double-free, invalid free +</ul> +Typical slowdown introduced by AddressSanitizer is <b>2x</b>. + +<h2 id="howtobuild">How to build</h2> +Follow the <a href="../get_started.html">clang build instructions</a>. <BR> +Note: CMake build does not work yet. +See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>. + +<h2 id="usage">Usage</h2> +Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR> +To get a reasonable performance add <tt>-O1</tt> or higher. <BR> +To get nicer stack traces in error messages add +<tt>-fno-omit-frame-pointer</tt>. <BR> +To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call +elimination (</tt>-fno-optimize-sibling-calls</tt>). + +<pre> +% cat example_UseAfterFree.cc +int main(int argc, char **argv) { + int *array = new int[100]; + delete [] array; + return array[argc]; // BOOM +} +</pre> + +<pre> +% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc +</pre> + +If a bug is detected, the program will print an error message to stderr and exit with a +non-zero exit code. +Currently, AddressSanitizer does not symbolize its output, so you may need to use a +separate script to symbolize the result offline (this will be fixed in future). +<pre> +% ./a.out 2> log +% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt +==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 +READ of size 4 at 0x7f7ddab8c084 thread T0 + #0 0x403c8c in main example_UseAfterFree.cc:4 + #1 0x7f7ddabcac4d in __libc_start_main ??:0 +0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) +freed by thread T0 here: + #0 0x404704 in operator delete[](void*) ??:0 + #1 0x403c53 in main example_UseAfterFree.cc:4 + #2 0x7f7ddabcac4d in __libc_start_main ??:0 +previously allocated by thread T0 here: + #0 0x404544 in operator new[](unsigned long) ??:0 + #1 0x403c43 in main example_UseAfterFree.cc:2 + #2 0x7f7ddabcac4d in __libc_start_main ??:0 +==9442== ABORTING +</pre> + +<h3 id="has_feature">__has_feature(address_sanitizer)</h3> +In some cases one may need to execute different code depending on whether +AddressSanitizer is enabled. +<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a> +can be used for this purpose. +<pre> +#if defined(__has_feature) && __has_feature(address_sanitizer) + code that runs only under AddressSanitizer +#else + code that does not run under AddressSanitizer +#endif +</pre> + +<h2 id="platforms">Supported Platforms</h2> +AddressSanitizer is supported on +<ul><li>Linux x86_64 (tested on Ubuntu 10.04). +<li>MacOS 10.6 i386/x86_64. +</ul> +Support for Linux i386/ARM and MacOS 10.7 is in progress +(it may work, but is not guaranteed too). + + +<h2 id="limitations">Limitations</h2> +<ul> + <li> AddressSanitizer uses more real memory than a native run. + How much -- depends on the allocations sizes. The smaller the + allocations you make the bigger the overhead. + <li> On 64-bit platforms AddressSanitizer maps (but not reserves) + 16+ Terabytes of virtual address space. + This means that tools like <tt>ulimit</tt> may not work as usually expected. + <li> Static linking is not supported. +</ul> + + +<h2 id="status">Current Status</h2> +AddressSanitizer is fully functional on supported platforms in LLVM head. +However, the test suite is not fully integrated yet and we lack the testing +process (buildbots). + +<h2 id="moreinfo">More Information</h2> +<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>. + + +</div> +</body> +</html> diff --git a/docs/AnalyzerRegions.html b/docs/AnalyzerRegions.html index 35708d5..f9d3337 100644 --- a/docs/AnalyzerRegions.html +++ b/docs/AnalyzerRegions.html @@ -1,3 +1,5 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>Static Analyzer Design Document: Memory Regions</title> @@ -59,7 +61,7 @@ of structures) then the StoreManager can simply return 'unknown' (represented by 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.</pp> +that internally reason about program memory in very different ways.</p> <p>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 @@ -102,7 +104,7 @@ typedef struct s my_type; void *p; int *q = (int*) p; char *r = (char*) p; -</pre +</pre> <p>Thus we need to canonicalize the MemRegion which is used in binding and retrieving.</p> diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html index bc78457..1416df5 100644 --- a/docs/AutomaticReferenceCounting.html +++ b/docs/AutomaticReferenceCounting.html @@ -1,8 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>Objective-C Automatic Reference Counting (ARC)</title> -<link type="text/css" rel="stylesheet" href="../menu.css" /> -<link type="text/css" rel="stylesheet" href="../content.css" /> +<link type="text/css" rel="stylesheet" href="../menu.css"> +<link type="text/css" rel="stylesheet" href="../content.css"> <style type="text/css"> /* Collapse the items in the ToC to the left. */ div#toc ul { @@ -18,6 +20,16 @@ div.rationale em { font-style: normal } +/* Revisions are also italicized. */ +span.revision { + font-style: italic +} + +span.whenRevised { + font-weight: bold; + font-style: normal +} + div h1 { font-size: 2em; margin: .67em 0 } div div h1 { font-size: 1.5em; margin: .75em 0 } div div div h1 { font-size: 1.17em; margin: .83em 0 } @@ -26,7 +38,7 @@ div div div div h1 { margin: 1.12em 0 } span.term { font-style: italic; font-weight: bold } </style> -<script lang="javascript"> +<script type="text/javascript"> /// A little script to recursively build a table of contents. function buildTOC(div, toc, ancestry) { var children = div.childNodes; @@ -207,6 +219,38 @@ adjusting the reference count, not by calling <tt>Block_copy</tt>.</p> </div> <!-- meta.background --> +<div id="meta.evolution"> +<h1>Evolution</h1> + +<p>ARC is under continual evolution, and this document must be updated +as the language progresses.</p> + +<p>If a change increases the expressiveness of the language, for +example by lifting a restriction or by adding new syntax, the change +will be annotated with a revision marker, like so:</p> + +<blockquote> + ARC applies to Objective-C pointer types, block pointer types, and + <span class="revision"><span class="whenRevised">[beginning Apple + 8.0, LLVM 3.8]</span> BPTRs declared within <code>extern + "BCPL"</code> blocks</span>. +</blockquote> + +<p>For now, it is sensible to version this document by the releases of +its sole implementation (and its host project), clang. +<q>LLVM X.Y</q> refers to an open-source release of clang from the +LLVM project. <q>Apple X.Y</q> refers to an Apple-provided release of +the Apple LLVM Compiler. Other organizations that prepare their own, +separately-versioned clang releases and wish to maintain similar +information in this document should send requests to cfe-dev.</p> + +<p>If a change decreases the expressiveness of the language, for +example by imposing a new restriction, this should be taken as an +oversight in the original specification and something to be avoided +in all versions. Such changes are generally to be avoided.</p> + +</div> <!-- meta.evolution --> + </div> <!-- meta --> <div id="general"> @@ -214,8 +258,10 @@ adjusting the reference count, not by calling <tt>Block_copy</tt>.</p> <p>Automatic Reference Counting implements automatic memory management for Objective-C objects and blocks, freeing the programmer from the -need explicitly insert retains and releases. It does not provide a -cycle collector; users must explicitly manage lifetime instead.</p> +need to explicitly insert retains and releases. It does not provide a +cycle collector; users must explicitly manage the lifetime of their +objects, breaking cycles manually or with weak or unsafe +references.</p> <p>ARC may be explicitly enabled with the compiler flag <tt>-fobjc-arc</tt>. It may also be explicitly disabled with the @@ -227,7 +273,7 @@ appearing on the compile line <q>wins</q>.</p> see the <a href="LanguageExtensions.html#__has_feature_extension">language extensions</a> document.</p> -</div> +</div> <!-- general --> <div id="objects"> <h1>Retainable object pointers</h1> @@ -444,9 +490,9 @@ The rule about function calls is really just an application of the existing C/C++ rule about calling functions through an incompatible function type, but it's useful to state it explicitly.</p></div> -</div> +</div> <!-- objects.operands.consumed --> -<div id="objects.operands.retained_returns"> +<div id="objects.operands.retained-returns"> <h1>Retained return values</h1> <p>A function or method which returns a retainable object pointer type @@ -481,7 +527,6 @@ and <tt>new</tt> <a href="#family">families</a> are implicitly marked <tt>__attribute__((ns_returns_retained))</tt>. This may be suppressed by explicitly marking the method <tt>__attribute__((ns_returns_not_retained))</tt>.</p> -</div> <p>It is undefined behavior if the method to which an Objective-C message send statically resolves has different retain semantics on its @@ -496,6 +541,7 @@ Again, the rule about function calls is really just an application of the existing C/C++ rule about calling functions through an incompatible function type.</p></div> +</div> <!-- objects.operands.retained-returns --> <div id="objects.operands.other-returns"> <h1>Unretained return values</h1> @@ -528,7 +574,8 @@ that it returns a pointer which is guaranteed to be valid at least as long as the innermost autorelease pool. There are no additional semantics enforced in the definition of such a method; it merely enables optimizations in callers.</p> -</div> + +</div> <!-- objects.operands.other-returns --> <div id="objects.operands.casts"> <h1>Bridged casts</h1> @@ -567,9 +614,9 @@ object pointers</a>.</p> cast purely to convince ARC to emit an unbalanced retain or release, respectively, is poor form.</p> -</div> +</div> <!-- objects.operands.casts --> -</div> +</div> <!-- objects.operands --> <div id="objects.restrictions"> <h1>Restrictions</h1> @@ -581,7 +628,7 @@ respectively, is poor form.</p> convert a value of retainable object pointer type to any non-retainable type, or vice-versa, is ill-formed. For example, an Objective-C object pointer shall not be converted to <tt>void*</tt>. -As an exception, cast to <tt>intptr_t</tt> is allowed becuase such +As an exception, cast to <tt>intptr_t</tt> is allowed because such casts are not transferring ownership. The <a href="#objects.operands.casts">bridged casts</a> may be used to perform these conversions where necessary.</p> @@ -591,28 +638,125 @@ management of the lifetime of objects if they may be freely passed around as unmanaged types. The bridged casts are provided so that the programmer may explicitly describe whether the cast transfers control into or out of ARC.</p></div> -</div> -<p>An unbridged cast to a retainable object pointer type of the return -value of a Objective-C message send which yields a non-retainable -pointer is treated as a <tt>__bridge_transfer</tt> cast -if:</p> +<p>However, the following exceptions apply.</p> + +</div> <!-- objects.restrictions.conversion --> + +<div id="objects.restrictions.conversion-exception-known"> +<h1>Conversion to retainable object pointer type of + expressions with known semantics</h1> +<p><span class="revision"><span class="whenRevised">[beginning Apple + 4.0, LLVM 3.1]</span> These exceptions have been greatly expanded; + they previously applied only to a much-reduced subset which is + difficult to categorize but which included null pointers, message + sends (under the given rules), and the various global constants.</span></p> + +<p>An unbridged conversion to a retainable object pointer type from a +type other than a retainable object pointer type is ill-formed, as +discussed above, unless the operand of the cast has a syntactic form +which is known retained, known unretained, or known +retain-agnostic.</p> + +<p>An expression is <span class="term">known retain-agnostic</span> if +it is:</p> <ul> -<li>the method has the <tt>cf_returns_retained</tt> attribute, or if -not that,</li> -<li>the method does not have the <tt>cf_returns_not_retained</tt> -attribute and</li> -<li>the method's <a href="#family">selector family</a> would imply -the <tt>ns_returns_retained</tt> attribute on a method which returned -a retainable object pointer type.</li> +<li>an Objective-C string literal,</li> +<li>a load from a <tt>const</tt> system global variable of +<a href="#misc.c-retainable">C retainable pointer type</a>, or</li> +<li>a null pointer constant.</li> </ul> -<p>Otherwise the cast is treated as a <tt>__bridge</tt> cast.</p> +<p>An expression is <span class="term">known unretained</span> if it +is an rvalue of <a href="#misc.c-retainable">C retainable +pointer type</a> and it is:</p> +<ul> +<li>a direct call to a function, and either that function has the + <tt>cf_returns_not_retained</tt> attribute or it is an + <a href="#misc.c-retainable.audit">audited</a> function that does not + have the <tt>cf_returns_retained</tt> attribute and does not follow + the create/copy naming convention,</li> +<li>a message send, and the declared method either has + the <tt>cf_returns_not_retained</tt> attribute or it has neither + the <tt>cf_returns_retained</tt> attribute nor a + <a href="#family">selector family</a> that implies a retained + result.</li> +</ul> -</div> +<p>An expression is <span class="term">known retained</span> if it is +an rvalue of <a href="#misc.c-retainable">C retainable pointer type</a> +and it is:</p> +<ul> +<li>a message send, and the declared method either has the + <tt>cf_returns_retained</tt> attribute, or it does not have + the <tt>cf_returns_not_retained</tt> attribute but it does have a + <a href="#family">selector family</a> that implies a retained + result.</li> +</ul> -</div> +<p>Furthermore:</p> +<ul> +<li>a comma expression is classified according to its right-hand side,</li> +<li>a statement expression is classified according to its result +expression, if it has one,</li> +<li>an lvalue-to-rvalue conversion applied to an Objective-C property +lvalue is classified according to the underlying message send, and</li> +<li>a conditional operator is classified according to its second and +third operands, if they agree in classification, or else the other +if one is known retain-agnostic.</li> +</ul> + +<p>If the cast operand is known retained, the conversion is treated as +a <tt>__bridge_transfer</tt> cast. If the cast operand is known +unretained or known retain-agnostic, the conversion is treated as +a <tt>__bridge</tt> cast.</p> + +<div class="rationale"><p>Rationale: Bridging casts are annoying. +Absent the ability to completely automate the management of CF +objects, however, we are left with relatively poor attempts to reduce +the need for a glut of explicit bridges. Hence these rules.</p> + +<p>We've so far consciously refrained from implicitly turning retained +CF results from function calls into <tt>__bridge_transfer</tt> casts. +The worry is that some code patterns — for example, creating a +CF value, assigning it to an ObjC-typed local, and then +calling <tt>CFRelease</tt> when done — are a bit too likely to +be accidentally accepted, leading to mysterious behavior.</p></div> + +</div> <!-- objects.restrictions.conversion-exception-known --> + +<div id="objects.restrictions.conversion-exception-contextual"> +<h1>Conversion from retainable object pointer type in certain contexts</h1> + +<p><span class="revision"><span class="whenRevised">[beginning Apple + 4.0, LLVM 3.1]</span></span></p> + +<p>If an expression of retainable object pointer type is explicitly +cast to a <a href="#misc.c-retainable">C retainable pointer type</a>, +the program is ill-formed as discussed above unless the result is +immediately used:</p> + +<ul> +<li>to initialize a parameter in an Objective-C message send where the +parameter is not marked with the <tt>cf_consumed</tt> attribute, or</li> +<li>to initialize a parameter in a direct call to +an <a href="#misc.c-retainable.audit">audited</a> function where the +parameter is not marked with the <tt>cf_consumed</tt> attribute.</li> +</ul> + +<div class="rationale"><p>Rationale: Consumed parameters are left out +because ARC would naturally balance them with a retain, which was +judged too treacherous. This is in part because several of the most +common consuming functions are in the <tt>Release</tt> family, and it +would be quite unfortunate for explicit releases to be silently +balanced out in this way.</p></div> + +</div> <!-- objects.restrictions.conversion-exception-contextual --> + +</div> <!-- objects.restrictions --> + +</div> <!-- objects --> <div id="ownership"> <h1>Ownership qualification</h1> @@ -721,6 +865,29 @@ already exists, then its ownership qualification must equal the ownership of the property; otherwise, the instance variable is created with that ownership qualification.</p> +<p>A property of retainable object pointer type which is synthesized +without a source of ownership has the ownership of its associated +instance variable, if it already exists; otherwise, +<span class="revision"><span class="whenRevised">[beginning Apple 3.1, +LLVM 3.1]</span> its ownership is implicitly <tt>strong</tt></span>. +Prior to this revision, it was ill-formed to synthesize such a +property.</p> + +<div class="rationale"><p>Rationale: using <tt>strong</tt> by default +is safe and consistent with the generic ARC rule about +<a href="#ownership.inference.variables">inferring ownership</a>. It +is, unfortunately, inconsistent with the non-ARC rule which states +that such properties are implicitly <tt>assign</tt>. However, that +rule is clearly untenable in ARC, since it leads to default-unsafe +code. The main merit to banning the properties is to avoid confusion +with non-ARC practice, which did not ultimately strike us as +sufficient to justify requiring extra syntax and (more importantly) +forcing novices to understand ownership rules just to declare a +property when the default is so reasonable. Changing the rule away +from non-ARC practice was acceptable because we had conservatively +banned the synthesis in order to give ourselves exactly this +leeway.</p></div> + </div> <!-- ownership.spelling.property --> </div> <!-- ownership.spelling --> @@ -739,7 +906,7 @@ semantics as the respective operation would have on an <tt>void*</tt> lvalue with the same alignment and non-ownership qualification.</p> <p><span class="term">Reading</span> occurs when performing a -lvalue-to-rvalue conversion on an object lvalue. +lvalue-to-rvalue conversion on an object lvalue.</p> <ul> <li>For <tt>__weak</tt> objects, the current pointee is retained and @@ -749,10 +916,9 @@ release of the pointee.</li> <li>For all other objects, the lvalue is loaded with primitive semantics.</li> </ul> -</p> <p><span class="term">Assignment</span> occurs when evaluating -an assignment operator. The semantics vary based on the qualification: +an assignment operator. The semantics vary based on the qualification:</p> <ul> <li>For <tt>__strong</tt> objects, the new pointee is first retained; second, the lvalue is loaded with primitive semantics; third, the new @@ -761,21 +927,20 @@ finally, the old pointee is released. This is not performed atomically; external synchronization must be used to make this safe in the face of concurrent loads and stores.</li> <li>For <tt>__weak</tt> objects, the lvalue is updated to point to the -new pointee, unless that object is currently undergoing deallocation, -in which case it the lvalue is updated to a null pointer. This must -execute atomically with respect to other assignments to the object, to -reads from the object, and to the final release of the new pointed-to -value.</li> +new pointee, unless the new pointee is an object currently undergoing +deallocation, in which case the lvalue is updated to a null pointer. +This must execute atomically with respect to other assignments to the +object, to reads from the object, and to the final release of the new +pointee.</li> <li>For <tt>__unsafe_unretained</tt> objects, the new pointee is stored into the lvalue using primitive semantics.</li> <li>For <tt>__autoreleasing</tt> objects, the new pointee is retained, autoreleased, and stored into the lvalue using primitive semantics.</li> </ul> -</p> <p><span class="term">Initialization</span> occurs when an object's lifetime begins, which depends on its storage duration. -Initialization proceeds in two stages: +Initialization proceeds in two stages:</p> <ol> <li>First, a null pointer is stored into the lvalue using primitive semantics. This step is skipped if the object @@ -784,7 +949,6 @@ is <tt>__unsafe_unretained</tt>.</li> evaluated and then assigned into the object using the usual assignment semantics.</li> </ol> -</p> <p><span class="term">Destruction</span> occurs when an object's lifetime ends. In all cases it is semantically equivalent to @@ -842,7 +1006,9 @@ operation has a weak-unavailable type.</p> <h1>Storage duration of <tt>__autoreleasing</tt> objects</h1> <p>A program is ill-formed if it declares an <tt>__autoreleasing</tt> -object of non-automatic storage duration.</p> +object of non-automatic storage duration. A program is ill-formed +if it captures an <tt>__autoreleasing</tt> object in a block or, +unless by reference, in a C++11 lambda.</p> <div class="rationale"><p>Rationale: autorelease pools are tied to the current thread and scope by their nature. While it is possible to @@ -863,7 +1029,7 @@ is left.</p> <p>A program is ill-formed if an expression of type <tt>T*</tt> is converted, explicitly or implicitly, to the type <tt>U*</tt>, where <tt>T</tt> and <tt>U</tt> have different ownership -qualification, unless: +qualification, unless:</p> <ul> <li><tt>T</tt> is qualified with <tt>__strong</tt>, <tt>__autoreleasing</tt>, or <tt>__unsafe_unretained</tt>, and @@ -876,9 +1042,8 @@ qualification, unless: <li>the conversion is a well-formed <a href="#ownership.restrictions.pass_by_writeback">pass-by-writeback</a>.</li> </ul> -</p> -<p>The analogous rule applies to <tt>T&</tt> and <tt>U&</tt> in +<p>The analogous rule applies to <tt>T&</tt> and <tt>U&</tt> in Objective-C++.</p> <div class="rationale"><p>Rationale: these rules provide a reasonable @@ -933,7 +1098,7 @@ where <tt>oq</tt> is an ownership qualifier, then the argument is a candidate for <span class="term">pass-by-writeback</span> if:</p> <ul> -<li><tt>oq</tt> is <tt>__strong</tt> or <tt>__weak</tt>, and +<li><tt>oq</tt> is <tt>__strong</tt> or <tt>__weak</tt>, and</li> <li>it would be legal to initialize a <tt>T __strong *</tt> with a <tt>U __strong *</tt>.</li> </ul> @@ -946,7 +1111,7 @@ implicit conversion sequence not requiring a pass-by-writeback.</p> not have a legal form:</p> <ul> -<li><tt>&var</tt>, where <tt>var</tt> is a scalar variable of +<li><tt>&var</tt>, where <tt>var</tt> is a scalar variable of automatic storage duration with retainable object pointer type</li> <li>a conditional expression where the second and third operands are both legal forms</li> @@ -963,7 +1128,7 @@ that the user will see confusing aliasing problems due to the implementation, below, where their store to the writeback temporary is not immediately seen in the original argument variable.</p></div> -<p>A pass-by-writeback is evaluated as follows: +<p>A pass-by-writeback is evaluated as follows:</p> <ol> <li>The argument is evaluated to yield a pointer <tt>p</tt> of type <tt>U oq *</tt>.</li> @@ -971,14 +1136,14 @@ not immediately seen in the original argument variable.</p></div> the argument, and no further work is required for the pass-by-writeback.</li> <li>Otherwise, a temporary of type <tt>T __autoreleasing</tt> is created and initialized to a null pointer.</li> -<li>If the argument is not an Objective-C method parameter marked +<li>If the parameter is not an Objective-C method parameter marked <tt>out</tt>, then <tt>*p</tt> is read, and the result is written into the temporary with primitive semantics.</li> <li>The address of the temporary is passed as the argument to the actual call.</li> <li>After the call completes, the temporary is loaded with primitive semantics, and that value is assigned into <tt>*p</tt>.</li> -</ol></p> +</ol> <div class="rationale"><p>Rationale: this is all admittedly convoluted. In an ideal world, we would see that a local variable is @@ -1006,20 +1171,20 @@ with a <tt>void*</tt> or an <tt>__unsafe_unretained</tt> object.</p></div> <p>This restriction does not apply in Objective-C++. However, -nontrivally ownership-qualified types are considered non-POD: in C++0x +nontrivally ownership-qualified types are considered non-POD: in C++11 terms, they are not trivially default constructible, copy constructible, move constructible, copy assignable, move assignable, -or destructible. It is a violation of C++ One Definition Rule to use -a class outside of ARC that, under ARC, would have an +or destructible. It is a violation of C++'s One Definition Rule to use +a class outside of ARC that, under ARC, would have a nontrivially ownership-qualified member.</p> <div class="rationale"><p>Rationale: unlike in C, we can express all the necessary ARC semantics for ownership-qualified subobjects as suboperations of the (default) special member functions for the class. These functions then become non-trivial. This has the non-obvious -repercussion that the class will have a non-trivial copy constructor -and non-trivial destructor; if it wouldn't outside of ARC, this means -that objects of the type will be passed and returned in an +result that the class will have a non-trivial copy constructor and +non-trivial destructor; if this would not normally be true outside of +ARC, objects of the type will be passed and returned in an ABI-incompatible manner.</p></div> </div> @@ -1055,7 +1220,6 @@ it is implicitly qualified with <tt>__unsafe_unretained</tt>;</li> <li>otherwise, it is implicitly qualified with <tt>__autoreleasing</tt>.</li> </ul> -</p> <div class="rationale"><p>Rationale: <tt>__autoreleasing</tt> exists mostly for this case, the Cocoa convention for out-parameters. Since @@ -1101,7 +1265,7 @@ template argument was deduced or explicitly specified. </p> family</span>, which is a conventional set of behaviors ascribed to it by the Cocoa conventions.</p> -<p>A method is in a certain method family if: +<p>A method is in a certain method family if:</p> <ul> <li>it has a <tt>objc_method_family</tt> attribute placing it in that family; or if not that,</li> @@ -1109,7 +1273,7 @@ by the Cocoa conventions.</p> it in a different or no family, and</li> <li>its selector falls into the corresponding selector family, and</li> <li>its signature obeys the added restrictions of the method family.</li> -</ul></p> +</ul> <p>A selector is in a certain selector family if, ignoring any leading underscores, the first component of the selector either consists @@ -1132,7 +1296,7 @@ declares or contains a call to an <tt>init</tt> method whose return type is neither <tt>id</tt> nor a pointer to a super-class or sub-class of the declaring class (if the method was declared on a class) or the static receiver type of the call (if it was declared -on a protocol).</p> +on a protocol). <div class="rationale"><p>Rationale: there are a fair number of existing methods with <tt>init</tt>-like selectors which nonetheless don't @@ -1189,7 +1353,7 @@ mechanical system, they are only imperfectly kept, especially as they haven't always even been precisely defined. While it is possible to define low-level ownership semantics with attributes like <tt>ns_returns_retained</tt>, this attribute allows the user to -communicate semantic intent, which of use both to ARC (which, e.g., +communicate semantic intent, which is of use both to ARC (which, e.g., treats calls to <tt>init</tt> specially) and the static analyzer.</p></div> </div> @@ -1281,7 +1445,7 @@ of ARC.</p> more prone than most code to signature errors, i.e. errors where a call was emitted against one method signature, but the implementing method has an incompatible signature. Having more precise type -information helps drastically lower this risks, as well as catching +information helps drastically lower this risk, as well as catching a number of latent bugs.</p></div> </div> <!-- family.semantics.result_type --> @@ -1348,7 +1512,7 @@ clearer.</p></div> </div> <!-- optimization.precise --> -</div> +</div> <!-- optimization --> <div id="misc"> <h1>Miscellaneous</h1> @@ -1361,14 +1525,13 @@ clearer.</p></div> <p>A program is ill-formed if it contains a method definition, message send, or <tt>@selector</tt> expression for any of the following -selectors: +selectors:</p> <ul> <li><tt>autorelease</tt></li> <li><tt>release</tt></li> <li><tt>retain</tt></li> <li><tt>retainCount</tt></li> </ul> -</p> <div class="rationale"><p>Rationale: <tt>retainCount</tt> is banned because ARC robs it of consistent semantics. The others were banned @@ -1482,9 +1645,12 @@ implementation.</p></div> <p>The <tt>self</tt> parameter variable of an Objective-C method is never actually retained by the implementation. It is undefined behavior, or at least dangerous, to cause an object to be deallocated -during a message send to that object. To make this -safe, <tt>self</tt> is implicitly <tt>const</tt> unless the method is -in the <a href="#family.semantics.init"><tt>init</tt> family</a>.</p> +during a message send to that object.</p> + +<p>To make this safe, for Objective-C instance methods <tt>self</tt> is +implicitly <tt>const</tt> unless the method is in the <a +href="#family.semantics.init"><tt>init</tt> family</a>. Further, <tt>self</tt> +is <b>always</b> implicitly <tt>const</tt> within a class method.</p> <div class="rationale"><p>Rationale: the cost of retaining <tt>self</tt> in all methods was found to be prohibitive, as @@ -1516,9 +1682,9 @@ retained during enumeration, and the collection itself cannot be synchronously modified. It can be overridden by explicitly qualifying the variable with <tt>__strong</tt>, which will make the variable mutable again and cause the loop to retain the objects it -encounters.</div> +encounters.</p></div> -</div> +</div> <!-- misc.enumeration --> <div id="misc.blocks"> <h1>Blocks</h1> @@ -1537,7 +1703,7 @@ retain during capture.</p> <p><tt>__block</tt> variables of retainable object owner type are moved off the stack by initializing the heap copy with the result of -moving from the stack copy.</tt></p> +moving from the stack copy.</p> <p>With the exception of retains done as part of initializing a <tt>__strong</tt> parameter variable or reading a <tt>__weak</tt> @@ -1552,7 +1718,7 @@ used only as an argument to a call.</p> <h1>Exceptions</h1> <p>By default in Objective C, ARC is not exception-safe for normal -releases: +releases:</p> <ul> <li>It does not end the lifetime of <tt>__strong</tt> variables when their scopes are abnormally terminated by an exception.</li> @@ -1645,6 +1811,87 @@ user with good cheer.</p></div> </div> <!-- misc.interior --> +<div id="misc.c-retainable"> +<h1>C retainable pointer types</h1> + +<p>A type is a <span class="term">C retainable pointer type</span> +if it is a pointer to (possibly qualified) <tt>void</tt> or a +pointer to a (possibly qualifier) <tt>struct</tt> or <tt>class</tt> +type.</p> + +<div class="rationale"><p>Rationale: ARC does not manage pointers of +CoreFoundation type (or any of the related families of retainable C +pointers which interoperate with Objective-C for retain/release +operation). In fact, ARC does not even know how to distinguish these +types from arbitrary C pointer types. The intent of this concept is +to filter out some obviously non-object types while leaving a hook for +later tightening if a means of exhaustively marking CF types is made +available.</p></div> + +<div id="misc.c-retainable.audit"> +<h1>Auditing of C retainable pointer interfaces</h1> + +<p><span class="revision"><span class="whenRevised">[beginning Apple 4.0, LLVM 3.1]</span></span></p> + +<p>A C function may be marked with the <tt>cf_audited_transfer</tt> +attribute to express that, except as otherwise marked with attributes, +it obeys the parameter (consuming vs. non-consuming) and return +(retained vs. non-retained) conventions for a C function of its name, +namely:</p> + +<ul> +<li>A parameter of C retainable pointer type is assumed to not be +consumed unless it is marked with the <tt>cf_consumed</tt> attribute, and</li> +<li>A result of C retainable pointer type is assumed to not be +returned retained unless the function is either +marked <tt>cf_returns_retained</tt> or it follows +the create/copy naming convention and is not +marked <tt>cf_returns_not_retained</tt>.</li> +</ul> + +<p>A function obeys the <span class="term">create/copy</span> naming +convention if its name contains as a substring:</p> +<ul> +<li>either <q>Create</q> or <q>Copy</q> not followed by a lowercase letter, or</li> +<li>either <q>create</q> or <q>copy</q> not followed by a lowercase +letter and not preceded by any letter, whether uppercase or lowercase.</li> +</ul> + +<p>A second attribute, <tt>cf_unknown_transfer</tt>, signifies that a +function's transfer semantics cannot be accurately captured using any +of these annotations. A program is ill-formed if it annotates the +same function with both <tt>cf_audited_transfer</tt> +and <tt>cf_unknown_transfer</tt>.</p> + +<p>A pragma is provided to faciliate the mass annotation of interfaces:</p> + +<pre>#pragma arc_cf_code_audited begin +... +#pragma arc_cf_code_audited end</pre> + +<p>All C functions declared within the extent of this pragma are +treated as if annotated with the <tt>cf_audited_transfer</tt> +attribute unless they otherwise have the <tt>cf_unknown_transfer</tt> +attribute. The pragma is accepted in all language modes. A program +is ill-formed if it attempts to change files, whether by including a +file or ending the current file, within the extent of this pragma.</p> + +<p>It is possible to test for all the features in this section with +<tt>__has_feature(arc_cf_code_audited)</tt>.</p> + +<div class="rationale"><p>Rationale: A significant inconvenience in +ARC programming is the necessity of interacting with APIs based around +C retainable pointers. These features are designed to make it +relatively easy for API authors to quickly review and annotate their +interfaces, in turn improving the fidelity of tools such as the static +analyzer and ARC. The single-file restriction on the pragma is +designed to eliminate the risk of accidentally annotating some other +header's interfaces.</p></div> + +</div> <!-- misc.c-retainable.audit --> + +</div> <!-- misc.c-retainable --> + </div> <!-- misc --> <div id="runtime"> diff --git a/docs/Block-ABI-Apple.txt b/docs/Block-ABI-Apple.txt index 661ed50..917059b 100644 --- a/docs/Block-ABI-Apple.txt +++ b/docs/Block-ABI-Apple.txt @@ -667,4 +667,3 @@ void _Block_object_assign(void *destAddr, const void *object, const int flags); 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); - diff --git a/docs/DriverInternals.html b/docs/DriverInternals.html index 380de99..ce707b9 100644 --- a/docs/DriverInternals.html +++ b/docs/DriverInternals.html @@ -1,8 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>Clang Driver Manual</title> - <link type="text/css" rel="stylesheet" href="../menu.css" /> - <link type="text/css" rel="stylesheet" href="../content.css" /> + <link type="text/css" rel="stylesheet" href="../menu.css"> + <link type="text/css" rel="stylesheet" href="../content.css"> <style type="text/css"> td { vertical-align: top; @@ -19,26 +21,29 @@ <ul> <li><a href="#intro">Introduction</a></li> - <li><a href="#features">Features and Goals</a></li> + <li><a href="#features">Features and Goals</a> <ul> <li><a href="#gcccompat">GCC Compatibility</a></li> <li><a href="#components">Flexible</a></li> <li><a href="#performance">Low Overhead</a></li> <li><a href="#simple">Simple</a></li> </ul> - <li><a href="#design">Design</a></li> + </li> + <li><a href="#design">Design</a> <ul> <li><a href="#int_intro">Internals Introduction</a></li> <li><a href="#int_overview">Design Overview</a></li> - <li><a href="#int_notes">Additional Notes</a></li> + <li><a href="#int_notes">Additional Notes</a> <ul> <li><a href="#int_compilation">The Compilation Object</a></li> <li><a href="#int_unified_parsing">Unified Parsing & Pipelining</a></li> <li><a href="#int_toolchain_translation">ToolChain Argument Translation</a></li> <li><a href="#int_unused_warnings">Unused Argument Warnings</a></li> </ul> + </li> <li><a href="#int_gcc_concepts">Relation to GCC Driver Concepts</a></li> </ul> + </li> </ul> @@ -168,11 +173,12 @@ distinct stages which manipulate these data structures, and the blue components are important helper classes. </p> - <center> - <a href="DriverArchitecture.png" alt="Driver Architecture Diagram"> - <img width=400 src="DriverArchitecture.png"> + <div style="text-align:center"> + <a href="DriverArchitecture.png"> + <img width=400 src="DriverArchitecture.png" + alt="Driver Architecture Diagram"> </a> - </center> + </div> <!--=======================================================================--> <h3><a name="int_stages">Driver Stages</a></h3> @@ -495,7 +501,7 @@ 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 <ii>Pipeline</ii> stage.</p> + the <i>Pipeline</i> stage.</p> </li> <li> diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 54f01fc..bd6af8d 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -1,8 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>"Clang" CFE Internals Manual</title> -<link type="text/css" rel="stylesheet" href="../menu.css" /> -<link type="text/css" rel="stylesheet" href="../content.css" /> +<link type="text/css" rel="stylesheet" href="../menu.css"> +<link type="text/css" rel="stylesheet" href="../content.css"> <style type="text/css"> td { vertical-align: top; @@ -19,7 +21,7 @@ td { <ul> <li><a href="#intro">Introduction</a></li> -<li><a href="#libsystem">LLVM System and Support Libraries</a></li> +<li><a href="#libsupport">LLVM Support Library</a></li> <li><a href="#libbasic">The Clang 'Basic' Library</a> <ul> <li><a href="#Diagnostics">The Diagnostics Subsystem</a></li> @@ -29,13 +31,9 @@ td { </ul> </li> <li><a href="#libdriver">The Driver Library</a> - <ul> - </ul> </li> <li><a href="#pch">Precompiled Headers</a> <li><a href="#libfrontend">The Frontend Library</a> - <ul> - </ul> </li> <li><a href="#liblex">The Lexer and Preprocessor Library</a> <ul> @@ -47,8 +45,6 @@ td { </ul> </li> <li><a href="#libparse">The Parser Library</a> - <ul> - </ul> </li> <li><a href="#libast">The AST Library</a> <ul> @@ -89,15 +85,13 @@ Clang, not for end-users. The description below is categorized by libraries, and does not describe any of the clients of the libraries.</p> <!-- ======================================================================= --> -<h2 id="libsystem">LLVM System and Support Libraries</h2> +<h2 id="libsupport">LLVM Support Library</h2> <!-- ======================================================================= --> -<p>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 <a -href="http://llvm.org/docs/ProgrammersManual.html">data-structures</a>, - including command line option -processing and various containers.</p> +<p>The LLVM libsupport library provides many underlying libraries and +<a href="http://llvm.org/docs/ProgrammersManual.html">data-structures</a>, +including command line option processing, various containers and a system +abstraction layer, which is used for file system access.</p> <!-- ======================================================================= --> <h2 id="libbasic">The Clang 'Basic' Library</h2> @@ -137,8 +131,8 @@ implemented. A representative example of a diagnostic is:</p> <pre> t.c:38:15: error: invalid operands to binary expression ('int *' and '_Complex float') - <font color="darkgreen">P = (P-42) + Gamma*4;</font> - <font color="blue">~~~~~~ ^ ~~~~~~~</font> + <span style="color:darkgreen">P = (P-42) + Gamma*4;</span> + <span style="color:blue">~~~~~~ ^ ~~~~~~~</span> </pre> <p>In this example, you can see the English translation, the severity (error), @@ -267,7 +261,7 @@ including variable names, types, labels, etc. The 'select' format can be used to achieve this sort of thing in a localizable way, see below.</p> <!-- ==================================== --> -<h4>Formatting a Diagnostic Argument</a></h4> +<h4>Formatting a Diagnostic Argument</h4> <!-- ==================================== --> <p>Arguments to diagnostics are fully typed internally, and come from a couple @@ -429,10 +423,10 @@ 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 from the C++ front end, where we warn about the right-shift operator changing -meaning from C++98 to C++0x:</p> +meaning from C++98 to C++11:</p> <pre> -test.cpp:3:7: warning: use of right-shift operator ('>>') in template argument will require parentheses in C++0x +test.cpp:3:7: warning: use of right-shift operator ('>>') in template argument will require parentheses in C++11 A<100 >> 2> *a; ^ ( ) @@ -577,7 +571,7 @@ the <code>CharSourceRange</code> class.</p> <!-- ======================================================================= --> <p>The clang Driver and library are documented <a -href="DriverInternals.html">here<a>.<p> +href="DriverInternals.html">here</a>.<p> <!-- ======================================================================= --> <h2 id="pch">Precompiled Headers</h2> @@ -687,7 +681,6 @@ lexer/preprocessor system on a per-token basis: <li><b>NeedsCleaning</b> - 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. - </p> </ol> </li> </ul> @@ -907,13 +900,13 @@ on the annotated lines. In this example, we expect to get:</p> <pre> <b>test.c:6:1: error: indirection requires pointer operand ('foo' invalid)</b> *X; // error -<font color="blue">^~</font> +<span style="color:blue">^~</span> <b>test.c:7:1: error: indirection requires pointer operand ('foo' invalid)</b> **Y; // error -<font color="blue">^~~</font> +<span style="color:blue">^~~</span> <b>test.c:8:1: error: indirection requires pointer operand ('foo' invalid)</b> **Z; // error -<font color="blue">^~~</font> +<span style="color:blue">^~~</span> </pre> <p>While this example is somewhat silly, it illustrates the point: we want to @@ -930,7 +923,7 @@ typedef for foo. <p>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 -<em>actual structure</em> of a type, ignoring typdefs. Second, we need an +<em>actual structure</em> of a type, ignoring typedefs. Second, we need an efficient way to query whether two types are structurally identical to each other, ignoring typedefs. The solution to both of these problems is the idea of canonical types.</p> @@ -1325,7 +1318,7 @@ extern "C" { <p>The transparent <code>DeclContexts</code> are:</p> <ul> - <li>Enumerations (but not C++0x "scoped enumerations"): + <li>Enumerations (but not C++11 "scoped enumerations"): <pre> enum Color { Red, @@ -1356,7 +1349,7 @@ LookupTable LT; LT.Vector = 0; // Okay: finds Vector inside the unnamed union </pre> </li> - <li>C++0x inline namespaces: + <li>C++11 inline namespaces: <pre> namespace mylib { inline namespace debug { @@ -1694,7 +1687,10 @@ interacts with constant evaluation:</p> any evaluatable subexpression to be accepted as an integer constant expression.</li> <li><b><tt>__builtin_constant_p</tt></b>: This returns true (as a integer - constant expression) if the operand is any evaluatable constant. As a + constant expression) if the operand evaluates to either a numeric value + (that is, not a pointer cast to integral type) of integral, enumeration, + floating or complex type, or if it evaluates to the address of the first + character of a string literal (possibly cast to some other type). As a special case, if <tt>__builtin_constant_p</tt> is the (potentially parenthesized) condition of a conditional operator expression ("?:"), only the true side of the conditional operator is considered, and it is evaluated @@ -1709,7 +1705,9 @@ 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> +<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> @@ -1723,7 +1721,7 @@ interacts with constant evaluation:</p> <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> +<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 @@ -1738,7 +1736,7 @@ 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 +will be synonymous. If you want to allow the <tt>[[]]</tt> C++11 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 diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html index c4a8047..68f0afc 100644 --- a/docs/LanguageExtensions.html +++ b/docs/LanguageExtensions.html @@ -11,6 +11,7 @@ td { vertical-align: top; } + th { background-color: #ffddaa; } </style> </head> <body> @@ -29,54 +30,59 @@ <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="#user_specified_system_framework">'User-Specified' System Frameworks</a></li> +<li><a href="#availability">Availability attribute</a></li> <li><a href="#checking_language_features">Checks for Standard Language Features</a> <ul> - <li><a href="#cxx_exceptions">C++ exceptions</a></li> - <li><a href="#cxx_rtti">C++ RTTI</a></li> + <li><a href="#cxx98">C++98</a> + <ul> + <li><a href="#cxx_exceptions">C++ exceptions</a></li> + <li><a href="#cxx_rtti">C++ RTTI</a></li> </ul></li> -<li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a> - <ul> - <li><a href="#cxx0x">C++0x</a> + <li><a href="#cxx11">C++11</a> <ul> - <li><a href="#cxx_access_control_sfinae">C++0x SFINAE includes access control</a></li> - <li><a href="#cxx_alias_templates">C++0x alias templates</a></li> - <li><a href="#cxx_alignas">C++0x alignment specifiers</a></li> - <li><a href="#cxx_attributes">C++0x attributes</a></li> - <li><a href="#cxx_constexpr">C++0x generalized constant expressions</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_delegating_constructor">C++0x delegating constructors</a></li> - <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li> - <li><a href="#cxx_explicit_conversions">C++0x explicit conversion functions</a></li> - <li><a href="#cxx_generalized_initializers">C++0x generalized initializers</a></li> - <li><a href="#cxx_implicit_moves">C++0x implicit move constructors/assignment operators</a></li> - <li><a href="#cxx_inheriting_constructors">C++0x inheriting constructors</a></li> - <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li> - <li><a href="#cxx_lambdas">C++0x lambdas</a></li> - <li><a href="#cxx_noexcept">C++0x noexcept specification</a></li> - <li><a href="#cxx_nonstatic_member_init">C++0x in-class non-static data member initialization</a></li> - <li><a href="#cxx_nullptr">C++0x nullptr</a></li> - <li><a href="#cxx_override_control">C++0x override control</a></li> - <li><a href="#cxx_range_for">C++0x range-based for loop</a></li> - <li><a href="#cxx_raw_string_literals">C++0x raw string literals</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_strong_enums">C++0x strongly-typed enumerations</a></li> - <li><a href="#cxx_trailing_return">C++0x trailing return type</a></li> - <li><a href="#cxx_unicode_literals">C++0x Unicode string literals</a></li> - <li><a href="#cxx_unrestricted_unions">C++0x unrestricted unions</a></li> - <li><a href="#cxx_user_literals">C++0x user-defined literals</a></li> - <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li> - </ul></li> - <li><a href="#c1x">C1X</a> + <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes access control</a></li> + <li><a href="#cxx_alias_templates">C++11 alias templates</a></li> + <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li> + <li><a href="#cxx_attributes">C++11 attributes</a></li> + <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li> + <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li> + <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li> + <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li> + <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li> + <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li> + <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li> + <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li> + <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li> + <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li> + <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li> + <li><a href="#cxx_lambdas">C++11 lambdas</a></li> + <li><a href="#cxx_local_type_template_args">C++11 local and unnamed types as template arguments</a></li> + <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li> + <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li> + <li><a href="#cxx_nullptr">C++11 nullptr</a></li> + <li><a href="#cxx_override_control">C++11 override control</a></li> + <li><a href="#cxx_range_for">C++11 range-based for loop</a></li> + <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li> + <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li> + <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li> + <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li> + <li><a href="#cxx_auto_type">C++11 type inference</a></li> + <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li> + <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li> + <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li> + <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li> + <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li> + <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li> + </ul></li> + <li><a href="#c11">C11</a> <ul> - <li><a href="#c_alignas">C1X alignment specifiers</a></li> - <li><a href="#c_generic_selections">C1X generic selections</a></li> - <li><a href="#c_static_assert">C1X <tt>_Static_assert()</tt></a></li> - </ul></li> - </ul> </li> + <li><a href="#c_alignas">C11 alignment specifiers</a></li> + <li><a href="#c_atomic">C11 atomic operations</a></li> + <li><a href="#c_generic_selections">C11 generic selections</a></li> + <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li> + </ul></li> +</ul></li> <li><a href="#checking_type_traits">Checks for Type Traits</a></li> <li><a href="#blocks">Blocks</a></li> <li><a href="#objc_features">Objective-C Features</a> @@ -84,6 +90,8 @@ <li><a href="#objc_instancetype">Related result types</a></li> <li><a href="#objc_arc">Automatic reference counting</a></li> <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li> + <li><a href="#objc_lambdas">Interoperability with C++11 lambdas</a></li> + <li><a href="#object-literals-subscripting">Object Literals and Subscripting</a></li> </ul> </li> <li><a href="#overloading-in-c">Function Overloading in C</a></li> @@ -101,7 +109,12 @@ </ul> </li> <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li> -<li><a href="#threadsafety">Thread Safety Annotation Checking</a></li> +<li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a> + <ul> + <li><a href="#address_sanitizer">AddressSanitizer</a></li> + </ul> +</li> +<li><a href="#threadsafety">Thread Safety Annotation Checking</a> <ul> <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li> <li><a href="#ts_lockable"><tt>lockable</tt></a></li> @@ -122,6 +135,7 @@ <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li> <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li> </ul> +</li> </ul> <!-- ======================================================================= --> @@ -192,12 +206,12 @@ language feature) or 0 if not. They can be used like this:</p> ... #if __has_feature(cxx_rvalue_references) -// This code will only be compiled with the -std=c++0x and -std=gnu++0x -// options, because rvalue references are only standardized in C++0x. +// This code will only be compiled with the -std=c++11 and -std=gnu++11 +// options, because rvalue references are only standardized in C++11. #endif #if __has_extension(cxx_rvalue_references) -// This code will be compiled with the -std=c++0x, -std=gnu++0x, -std=c++98 +// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 // and -std=gnu++98 options, because rvalue references are supported as a // language extension in C++98. #endif @@ -209,11 +223,21 @@ language feature) or 0 if not. They can be used like this:</p> non-standardized features, i.e. features not prefixed <code>c_</code>, <code>cxx_</code> or <code>objc_</code>.</p> +<p id="has_feature_for_non_language_features"> +Another use of <code>__has_feature</code> is to check for compiler features +not related to the language standard, such as e.g. +<a href="AddressSanitizer.html">AddressSanitizer</a>. + <p>If the <code>-pedantic-errors</code> option is given, <code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p> <p>The feature tag is described along with the language feature below.</p> +<p>The feature name or extension name can also be specified with a preceding and +following <code>__</code> (double underscore) to avoid interference from a macro +with the same name. For instance, <code>__cxx_rvalue_references__</code> can be +used instead of <code>cxx_rvalue_references</code>.</p> + <!-- ======================================================================= --> <h3><a name="__has_attribute">__has_attribute</a></h3> <!-- ======================================================================= --> @@ -238,6 +262,11 @@ can be used like this:</p> </pre> </blockquote> +<p>The attribute name can also be specified with a preceding and +following <code>__</code> (double underscore) to avoid interference from a macro +with the same name. For instance, <code>__always_inline__</code> can be used +instead of <code>always_inline</code>.</p> + <!-- ======================================================================= --> <h2 id="has_include">Include File Checking Macros</h2> <!-- ======================================================================= --> @@ -346,30 +375,36 @@ is used in the file argument.</p> <dd>Defined when compiling with Clang</dd> <dt><code>__clang_major__</code></dt> - <dd>Defined to the major version number of Clang (e.g., the 2 in - 2.0.1).</dd> + <dd>Defined to the major marketing version number of Clang (e.g., the + 2 in 2.0.1). Note that marketing version numbers should not be used to + check for language features, as different vendors use different numbering + schemes. Instead, use the <a href="#feature_check">feature checking + macros</a>.</dd> <dt><code>__clang_minor__</code></dt> <dd>Defined to the minor version number of Clang (e.g., the 0 in - 2.0.1).</dd> + 2.0.1). Note that marketing version numbers should not be used to + check for language features, as different vendors use different numbering + schemes. Instead, use the <a href="#feature_check">feature checking + macros</a>.</dd> <dt><code>__clang_patchlevel__</code></dt> - <dd>Defined to the patch level of Clang (e.g., the 1 in 2.0.1).</dd> + <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd> <dt><code>__clang_version__</code></dt> - <dd>Defined to a string that captures the Clang version, including - the Subversion tag or revision number, e.g., "1.5 (trunk - 102332)".</dd> + <dd>Defined to a string that captures the Clang marketing version, including + the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd> </dl> <!-- ======================================================================= --> <h2 id="vectors">Vectors and Extended Vectors</h2> <!-- ======================================================================= --> -<p>Supports the GCC vector extensions, plus some stuff like V[1].</p> +<p>Supports the GCC, OpenCL, AltiVec and NEON vector extensions.</p> -<p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw -syntax and other tidbits as seen in OpenCL. An example is:</p> +<p>OpenCL vector types are created using <tt>ext_vector_type</tt> attribute. It +support for <tt>V.xyzw</tt> syntax and other tidbits as seen in OpenCL. An +example is:</p> <blockquote> <pre> @@ -385,7 +420,161 @@ float4 foo(float2 a, float2 b) { </pre> </blockquote> -<p>Query for this feature with __has_extension(attribute_ext_vector_type).</p> +<p>Query for this feature with +<tt>__has_extension(attribute_ext_vector_type)</tt>.</p> + +<p>Giving <tt>-faltivec</tt> option to clang enables support for AltiVec vector +syntax and functions. For example:</p> + +<blockquote> +<pre> +vector float foo(vector int a) { + vector int b; + b = vec_add(a, a) + a; + return (vector float)b; +} +</pre> +</blockquote> + +<p>NEON vector types are created using <tt>neon_vector_type</tt> and +<tt>neon_polyvector_type</tt> attributes. For example:</p> + +<blockquote> +<pre> +typedef <b>__attribute__((neon_vector_type(8)))</b> int8_t int8x8_t; +typedef <b>__attribute__((neon_polyvector_type(16)))</b> poly8_t poly8x16_t; + +int8x8_t foo(int8x8_t a) { + int8x8_t v; + v = a; + return v; +} +</pre> +</blockquote> + +<!-- ======================================================================= --> +<h3><a name="vector_literals">Vector Literals</a></h3> +<!-- ======================================================================= --> + +<p>Vector literals can be used to create vectors from a set of scalars, or +vectors. Either parentheses or braces form can be used. In the parentheses form +the number of literal values specified must be one, i.e. referring to a scalar +value, or must match the size of the vector type being created. If a single +scalar literal value is specified, the scalar literal value will be replicated +to all the components of the vector type. In the brackets form any number of +literals can be specified. For example:</p> + +<blockquote> +<pre> +typedef int v4si __attribute__((__vector_size__(16))); +typedef float float4 __attribute__((ext_vector_type(4))); +typedef float float2 __attribute__((ext_vector_type(2))); + +v4si vsi = (v4si){1, 2, 3, 4}; +float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); +vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). +vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). +vector int vi3 = (vector int)(1, 2); // error +vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). +vector int vi5 = (vector int)(1, 2, 3, 4); +float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); +</pre> +</blockquote> + +<!-- ======================================================================= --> +<h3><a name="vector_operations">Vector Operations</a></h3> +<!-- ======================================================================= --> + +<p>The table below shows the support for each operation by vector extension. +A dash indicates that an operation is not accepted according to a corresponding +specification.</p> + +<table width="500" border="1" cellspacing="0"> + <tr> + <th>Operator</th> + <th>OpenCL</th> + <th>AltiVec</th> + <th>GCC</th> + <th>NEON</th> + </tr> + <tr> + <td>[]</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + </tr> + <tr> + <td>unary operators +, -</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + </tr> + <tr> + <td>++, --</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + <td align="center">-</td> + </tr> + <tr> + <td>+, -, *, /, %</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + </tr> + <tr> + <td>bitwise operators &, |, ^, ~</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + </tr> + <tr> + <td>>>, <<</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + </tr> + <tr> + <td>!, &&,||</td> + <td align="center">no</td> + <td align="center">-</td> + <td align="center">-</td> + <td align="center">-</td> + </tr> + <tr> + <td>==,!=, >, <, >=, <=</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">-</td> + <td align="center">-</td> + </tr> + <tr> + <td>=</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + </tr> + <tr> + <td>:?</td> + <td align="center">yes</td> + <td align="center">-</td> + <td align="center">-</td> + <td align="center">-</td> + </tr> + <tr> + <td>sizeof</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + <td align="center">yes</td> + </tr> +</table> <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p> @@ -404,7 +593,8 @@ and <tt>unavailable</tt> attributes. For example:</p> 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] +<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! + [-Wdeprecated-declarations] explode(); ^</pre> </blockquote> @@ -437,233 +627,334 @@ individual enumerators.</p> <p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p> <!-- ======================================================================= --> -<h2 id="checking_language_features">Checks for Standard Language Features</h2> +<h2 id="user_specified_system_framework">'User-Specified' System Frameworks</h2> <!-- ======================================================================= --> -<p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are -enabled. Those features are listed here.</p> +<p>Clang provides a mechanism by which frameworks can be built in such a way +that they will always be treated as being 'system frameworks', even if they are +not present in a system framework directory. This can be useful to system +framework developers who want to be able to test building other applications +with development builds of their framework, including the manner in which the +compiler changes warning behavior for system headers.</p> -<h3 id="cxx_exceptions">C++ exceptions</h3> +<p>Framework developers can opt-in to this mechanism by creating a +'.system_framework' file at the top-level of their framework. That is, the +framework should have contents like:</p> -<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For -example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p> +<pre> + .../TestFramework.framework + .../TestFramework.framework/.system_framework + .../TestFramework.framework/Headers + .../TestFramework.framework/Headers/TestFramework.h + ... +</pre> -<h3 id="cxx_rtti">C++ RTTI</h3> +<p>Clang will treat the presence of this file as an indicator that the framework +should be treated as a system framework, regardless of how it was found in the +framework search path. For consistency, we recommend that such files never be +included in installed versions of the framework.</p> -<p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example, -compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p> +<!-- ======================================================================= --> +<h2 id="availability">Availability attribute</h2 +<!-- ======================================================================= --> + +<p>Clang introduces the <code>availability</code> attribute, which can +be placed on declarations to describe the lifecycle of that +declaration relative to operating system versions. Consider the function declaration for a hypothetical function <code>f</code>:</p> + +<pre> +void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); +</pre> + +<p>The availability attribute states that <code>f</code> was introduced in Mac OS X 10.4, deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information is used by Clang to determine when it is safe to use <code>f</code>: for example, if Clang is instructed to compile code for Mac OS X 10.5, a call to <code>f()</code> succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call succeeds but Clang emits a warning specifying that the function is deprecated. Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call fails because <code>f()</code> is no longer available.</p> + +<p>The availablility attribute is a comma-separated list starting with the platform name and then including clauses specifying important milestones in the declaration's lifetime (in any order) along with additional information. Those clauses can be:</p> + +<dl> + <dt>introduced=<i>version</i></dt> + <dd>The first version in which this declaration was introduced.</dd> + + <dt>deprecated=<i>version</i></dt> + <dd>The first version in which this declaration was deprecated, meaning that users should migrate away from this API.</dd> + + <dt>obsoleted=<i>version</i></dt> + <dd>The first version in which this declaration was obsoleted, meaning that it was removed completely and can no longer be used.</dd> + + <dt>unavailable</dt> + <dd>This declaration is never available on this platform.</dd> + + <dt>message=<i>string-literal</i></dt> + <dd>Additional message text that Clang will provide when emitting a warning or error about use of a deprecated or obsoleted declaration. Useful to direct users to replacement APIs.</dd> +</dl> + +<p>Multiple availability attributes can be placed on a declaration, which may correspond to different platforms. Only the availability attribute with the platform corresponding to the target platform will be used; any others will be ignored. If no availability attribute specifies availability for the current target platform, the availability attributes are ignored. Supported platforms are:</p> + +<dl> + <dt>ios</dt> + <dd>Apple's iOS operating system. The minimum deployment target is specified by the <code>-mios-version-min=<i>version</i></code> or <code>-miphoneos-version-min=<i>version</i></code> command-line arguments.</dd> + + <dt>macosx</dt> + <dd>Apple's Mac OS X operating system. The minimum deployment target is specified by the <code>-mmacosx-version-min=<i>version</i></code> command-line argument.</dd> +</dl> + +<p>A declaration can be used even when deploying back to a platform +version prior to when the declaration was introduced. When this +happens, the declaration is <a + href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly +linked</a>, as if the <code>weak_import</code> attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.</p> <!-- ======================================================================= --> -<h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2> +<h2 id="checking_language_features">Checks for Standard Language Features</h2> <!-- ======================================================================= --> -<p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used -to query if certain upcoming standard language features are enabled. Those -features are listed here. Features that are not yet implemented will be -noted.</p> +<p>The <tt>__has_feature</tt> macro can be used to query if certain standard +language features are enabled. The <tt>__has_extension</tt> macro can be used +to query if language features are available as an extension when compiling for +a standard which does not provide them. The features which can be tested are +listed here.</p> + +<h3 id="cxx98">C++98</h3> + +<p>The features listed below are part of the C++98 standard. These features are +enabled by default when compiling C++ code.</p> + +<h4 id="cxx_exceptions">C++ exceptions</h4> -<h3 id="cxx0x">C++0x</h3> +<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For +example, compiling code with <tt>-fno-exceptions</tt> disables C++ exceptions.</p> + +<h4 id="cxx_rtti">C++ RTTI</h4> -<p>The features listed below are slated for inclusion in the upcoming -C++0x standard. As a result, all these features are enabled -with the <tt>-std=c++0x</tt> option when compiling C++ code.</p> +<p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example, +compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p> -<h4 id="cxx_access_control_sfinae">C++0x SFINAE includes access control</h4> +<h3 id="cxx11">C++11</h3> + +<p>The features listed below are part of the C++11 standard. As a result, all +these features are enabled with the <tt>-std=c++11</tt> or <tt>-std=gnu++11</tt> +option when compiling C++ code.</p> + +<h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4> <p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p> -<h4 id="cxx_alias_templates">C++0x alias templates</h4> +<h4 id="cxx_alias_templates">C++11 alias templates</h4> <p>Use <tt>__has_feature(cxx_alias_templates)</tt> or <tt>__has_extension(cxx_alias_templates)</tt> to determine if support for -C++0x's alias declarations and alias templates is enabled.</p> +C++11's alias declarations and alias templates is enabled.</p> -<h4 id="cxx_alignas">C++0x alignment specifiers</h4> +<h4 id="cxx_alignas">C++11 alignment specifiers</h4> <p>Use <tt>__has_feature(cxx_alignas)</tt> or <tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment specifiers using <tt>alignas</tt> is enabled.</p> -<h4 id="cxx_attributes">C++0x attributes</h4> +<h4 id="cxx_attributes">C++11 attributes</h4> <p>Use <tt>__has_feature(cxx_attributes)</tt> or <tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute -parsing with C++0x's square bracket notation is enabled.</p> +parsing with C++11's square bracket notation is enabled.</p> -<h4 id="cxx_constexpr">C++0x generalized constant expressions</h4> +<h4 id="cxx_constexpr">C++11 generalized constant expressions</h4> <p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support for generalized constant expressions (e.g., <tt>constexpr</tt>) is -enabled. Clang does not currently implement this feature.</p> +enabled.</p> -<h4 id="cxx_decltype">C++0x <tt>decltype()</tt></h4> +<h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4> <p>Use <tt>__has_feature(cxx_decltype)</tt> or <tt>__has_extension(cxx_decltype)</tt> to determine if support for the -<tt>decltype()</tt> specifier is enabled.</p> +<tt>decltype()</tt> specifier is enabled. C++11's <tt>decltype</tt> +does not require type-completeness of a function call expression. +Use <tt>__has_feature(cxx_decltype_incomplete_return_types)</tt> +or <tt>__has_extension(cxx_decltype_incomplete_return_types)</tt> +to determine if support for this feature is enabled.</p> -<h4 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h4> +<h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4> <p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or <tt>__has_extension(cxx_default_function_template_args)</tt> to determine if support for default template arguments in function templates is enabled.</p> -<h4 id="cxx_delegating_constructors">C++0x delegating constructors</h4> +<h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4> + +<p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or +<tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for +defaulted function definitions (with <tt>= default</tt>) is enabled.</p> + +<h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4> <p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if support for delegating constructors is enabled.</p> -<h4 id="cxx_deleted_functions">C++0x <tt>delete</tt>d functions</h4> +<h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4> <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or <tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for deleted function definitions (with <tt>= delete</tt>) is enabled.</p> -<h4 id="cxx_explicit_conversions">C++0x explicit conversion functions</h3> +<h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4> <p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p> -<h4 id="cxx_generalized_initializers">C++0x generalized initializers</h4> +<h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4> <p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if support for generalized initializers (using braced lists and -<tt>std::initializer_list</tt>) is enabled. Clang does not currently implement -this feature.</p> +<tt>std::initializer_list</tt>) is enabled.</p> -<h4 id="cxx_implicit_moves">C++0x implicit move constructors/assignment operators</h4> +<h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4> <p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will implicitly generate move constructors and move assignment operators where needed.</p> -<h4 id="cxx_inheriting_constructors">C++0x inheriting constructors</h4> +<h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4> <p>Use <tt>__has_feature(cxx_inheriting_constructors)</tt> to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.</p> -<h4 id="cxx_inline_namespaces">C++0x inline namespaces</h4> +<h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4> <p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or <tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for inline namespaces is enabled.</p> -<h4 id="cxx_lambdas">C++0x lambdas</h4> +<h4 id="cxx_lambdas">C++11 lambdas</h4> <p>Use <tt>__has_feature(cxx_lambdas)</tt> or <tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas -is enabled. Clang does not currently implement this feature.</p> +is enabled. </p> + +<h4 id="cxx_local_type_template_args">C++11 local and unnamed types as template arguments</h4> -<h4 id="cxx_noexcept">C++0x noexcept</h4> +<p>Use <tt>__has_feature(cxx_local_type_template_args)</tt> or +<tt>__has_extension(cxx_local_type_template_args)</tt> to determine if +support for local and unnamed types as template arguments is enabled.</p> + +<h4 id="cxx_noexcept">C++11 noexcept</h4> <p>Use <tt>__has_feature(cxx_noexcept)</tt> or <tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept exception specifications is enabled.</p> -<h4 id="cxx_nonstatic_member_init">C++0x in-class non-static data member initialization</h4> +<h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4> <p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p> -<h4 id="cxx_nullptr">C++0x <tt>nullptr</tt></h4> +<h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4> <p>Use <tt>__has_feature(cxx_nullptr)</tt> or <tt>__has_extension(cxx_nullptr)</tt> to determine if support for <tt>nullptr</tt> is enabled.</p> -<h4 id="cxx_override_control">C++0x <tt>override control</tt></h4> +<h4 id="cxx_override_control">C++11 <tt>override control</tt></h4> <p>Use <tt>__has_feature(cxx_override_control)</tt> or <tt>__has_extension(cxx_override_control)</tt> to determine if support for the override control keywords is enabled.</p> -<h4 id="cxx_reference_qualified_functions">C++0x reference-qualified functions</h4> +<h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4> <p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or <tt>__has_extension(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> -<h4 id="cxx_range_for">C++0x range-based <tt>for</tt> loop</h4> +<h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4> <p>Use <tt>__has_feature(cxx_range_for)</tt> or <tt>__has_extension(cxx_range_for)</tt> to determine if support for the range-based for loop is enabled. </p> -<h4 id="cxx_raw_string_literals">C++0x raw string literals</h4> -<p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support for raw string literals (e.g., <tt>R"foo\bar"</tt>) is enabled.</p> +<h4 id="cxx_raw_string_literals">C++11 raw string literals</h4> +<p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support +for raw string literals (e.g., <tt>R"x(foo\bar)x"</tt>) is enabled.</p> -<h4 id="cxx_rvalue_references">C++0x rvalue references</h4> +<h4 id="cxx_rvalue_references">C++11 rvalue references</h4> <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or <tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for rvalue references is enabled. </p> -<h4 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h4> +<h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4> <p>Use <tt>__has_feature(cxx_static_assert)</tt> or <tt>__has_extension(cxx_static_assert)</tt> to determine if support for compile-time assertions using <tt>static_assert</tt> is enabled.</p> -<h4 id="cxx_auto_type">C++0x type inference</h4> +<h4 id="cxx_auto_type">C++11 type inference</h4> <p>Use <tt>__has_feature(cxx_auto_type)</tt> or -<tt>__has_extension(cxx_auto_type)</tt> to determine C++0x type inference is +<tt>__has_extension(cxx_auto_type)</tt> to determine C++11 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> -<h4 id="cxx_strong_enums">C++0x strongly typed enumerations</h4> +<h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4> <p>Use <tt>__has_feature(cxx_strong_enums)</tt> or <tt>__has_extension(cxx_strong_enums)</tt> to determine if support for strongly typed, scoped enumerations is enabled.</p> -<h4 id="cxx_trailing_return">C++0x trailing return type</h4> +<h4 id="cxx_trailing_return">C++11 trailing return type</h4> <p>Use <tt>__has_feature(cxx_trailing_return)</tt> or <tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the alternate function declaration syntax with trailing return type is enabled.</p> -<h4 id="cxx_unicode_literals">C++0x Unicode string literals</h4> +<h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4> <p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if support for Unicode string literals is enabled.</p> -<h4 id="cxx_unrestricted_unions">C++0x unrestricted unions</h4> +<h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4> -<p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled. Clang does not currently support this feature.</p> +<p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled.</p> -<h4 id="cxx_user_literals">C++0x user-defined literals</h4> +<h4 id="cxx_user_literals">C++11 user-defined literals</h4> -<p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled. Clang does not currently support this feature.</p> +<p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled.</p> -<h4 id="cxx_variadic_templates">C++0x variadic templates</h4> +<h4 id="cxx_variadic_templates">C++11 variadic templates</h4> <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or <tt>__has_extension(cxx_variadic_templates)</tt> to determine if support for variadic templates is enabled.</p> -<h3 id="c1x">C1X</h3> +<h3 id="c11">C11</h3> -<p>The features listed below are slated for inclusion in the upcoming -C1X standard. As a result, all these features are enabled -with the <tt>-std=c1x</tt> option when compiling C code.</p> +<p>The features listed below are part of the C11 standard. As a result, all +these features are enabled with the <tt>-std=c11</tt> or <tt>-std=gnu11</tt> +option when compiling C code. Additionally, because these features are all +backward-compatible, they are available as extensions in all language modes.</p> -<h4 id="c_alignas">C1X alignment specifiers</h4> +<h4 id="c_alignas">C11 alignment specifiers</h4> <p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt> to determine if support for alignment specifiers using <tt>_Alignas</tt> is enabled.</p> -<h4 id="c_generic_selections">C1X generic selections</h4> +<h4 id="c_atomic">C11 atomic operations</h4> + +<p>Use <tt>__has_feature(c_atomic)</tt> or <tt>__has_extension(c_atomic)</tt> +to determine if support for atomic types using <tt>_Atomic</tt> is enabled. +Clang also provides <a href="#__c11_atomic">a set of builtins</a> which can be +used to implement the <tt><stdatomic.h></tt> operations on _Atomic +types.</p> + +<h4 id="c_generic_selections">C11 generic selections</h4> <p>Use <tt>__has_feature(c_generic_selections)</tt> or <tt>__has_extension(c_generic_selections)</tt> to determine if support for generic selections is enabled.</p> -<p>As an extension, the C1X generic selection expression is available in all +<p>As an extension, the C11 generic selection expression is available in all languages supported by Clang. The syntax is the same as that given in the -C1X draft standard.</p> +C11 standard.</p> <p>In C, type compatibility is decided according to the rules given in the appropriate standard, but in C++, which lacks the type compatibility rules used in C, types are considered compatible only if they are equivalent.</p> -<h4 id="c_static_assert">C1X <tt>_Static_assert()</tt></h4> +<h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4> <p>Use <tt>__has_feature(c_static_assert)</tt> or <tt>__has_extension(c_static_assert)</tt> to determine if support for @@ -707,7 +998,10 @@ struct is_convertible_to { <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> - <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++0x standard library.</li> + <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li> + <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++11 standard library.</li> + <li><code>__is_trivially_assignable(totype, fromtype)</code>: Determines whether a value of type <tt>totype</tt> can be assigned to from a value of type <tt>fromtype</tt> such that no non-trivial functions are called as part of that assignment. This trait is required to implement the C++11 standard library.</li> + <li><code>__is_trivially_constructible(type, argtypes...)</code>: Determines whether a value of type <tt>type</tt> can be direct-initialized with arguments of types <tt>argtypes...</tt> such that no non-trivial functions are called as part of that initialization. This trait is required to implement the C++11 standard library.</li> </ul> <!-- ======================================================================= --> @@ -771,7 +1065,7 @@ an Objective-C method, e.g.</p> <p>The related result type can also be inferred for some methods. To determine whether a method has an inferred related result type, the first word in the camel-case selector (e.g., "init" in "initWithObjects") is -considered, and the method will a related result type if its return +considered, and the method will have a related result type if its return type is compatible with the type of its class and if</p> <ul> @@ -814,7 +1108,7 @@ the <tt>instancetype</tt> contextual keyword is available.</p> <h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2> <!-- ======================================================================= --> -<p>Clang provides support for C++0x enumerations with a fixed +<p>Clang provides support for C++11 enumerations with a fixed underlying type within Objective-C. For example, one can write an enumeration type as:</p> @@ -829,6 +1123,72 @@ enumeration value, is <tt>unsigned char</tt>.</p> support for fixed underlying types is available in Objective-C.</p> <!-- ======================================================================= --> +<h2 id="objc_lambdas">Interoperability with C++11 lambdas</h2> +<!-- ======================================================================= --> + +<p>Clang provides interoperability between C++11 lambdas and +blocks-based APIs, by permitting a lambda to be implicitly converted +to a block pointer with the corresponding signature. For example, +consider an API such as <code>NSArray</code>'s array-sorting +method:</p> + +<pre> - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; </pre> + +<p><code>NSComparator</code> is simply a typedef for the block pointer +<code>NSComparisonResult (^)(id, id)</code>, and parameters of this +type are generally provided with block literals as arguments. However, +one can also use a C++11 lambda so long as it provides the same +signature (in this case, accepting two parameters of type +<code>id</code> and returning an <code>NSComparisonResult</code>):</p> + +<pre> + NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", + @"String 02"]; + const NSStringCompareOptions comparisonOptions + = NSCaseInsensitiveSearch | NSNumericSearch | + NSWidthInsensitiveSearch | NSForcedOrderingSearch; + NSLocale *currentLocale = [NSLocale currentLocale]; + NSArray *sorted + = [array sortedArrayUsingComparator:<b>[=](id s1, id s2) -> NSComparisonResult { + NSRange string1Range = NSMakeRange(0, [s1 length]); + return [s1 compare:s2 options:comparisonOptions + range:string1Range locale:currentLocale]; + }</b>]; + NSLog(@"sorted: %@", sorted); +</pre> + +<p>This code relies on an implicit conversion from the type of the +lambda expression (an unnamed, local class type called the <i>closure +type</i>) to the corresponding block pointer type. The conversion +itself is expressed by a conversion operator in that closure type +that produces a block pointer with the same signature as the lambda +itself, e.g.,</p> + +<pre> + operator NSComparisonResult (^)(id, id)() const; +</pre> + +<p>This conversion function returns a new block that simply forwards +the two parameters to the lambda object (which it captures by copy), +then returns the result. The returned block is first copied (with +<tt>Block_copy</tt>) and then autoreleased. As an optimization, if a +lambda expression is immediately converted to a block pointer (as in +the first example, above), then the block is not copied and +autoreleased: rather, it is given the same lifetime as a block literal +written at that point in the program, which avoids the overhead of +copying a block to the heap in the common case.</p> + +<p>The conversion from a lambda to a block pointer is only available +in Objective-C++, and not in C++ with blocks, due to its use of +Objective-C memory management (autorelease).</p> + +<!-- ======================================================================= --> +<h2 id="object-literals-subscripting">Object Literals and Subscripting</h2> +<!-- ======================================================================= --> + +<p>Clang provides support for <a href="ObjectiveCLiterals.html">Object Literals and Subscripting</a> in Objective-C, which simplifies common Objective-C programming patterns, makes programs more concise, and improves the safety of container creation. There are several feature macros associated with object literals and subscripting: <code>__has_feature(objc_array_literals)</code> tests the availability of array literals; <code>__has_feature(objc_dictionary_literals)</code> tests the availability of dictionary literals; <code>__has_feature(objc_subscripting)</code> tests the availability of object subscripting.</p> + +<!-- ======================================================================= --> <h2 id="overloading-in-c">Function Overloading in C</h2> <!-- ======================================================================= --> @@ -1103,6 +1463,32 @@ relying on the platform specific implementation details of __sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier. </p> +<!-- ======================================================================= --> +<h3><a name="__c11_atomic">__c11_atomic builtins</a></h3> +<!-- ======================================================================= --> + +<p>Clang provides a set of builtins which are intended to be used to implement +C11's <tt><stdatomic.h></tt> header. These builtins provide the semantics +of the <tt>_explicit</tt> form of the corresponding C11 operation, and are named +with a <tt>__c11_</tt> prefix. The supported operations are:</p> + +<ul> + <li><tt>__c11_atomic_init</tt></li> + <li><tt>__c11_atomic_thread_fence</tt></li> + <li><tt>__c11_atomic_signal_fence</tt></li> + <li><tt>__c11_atomic_is_lock_free</tt></li> + <li><tt>__c11_atomic_store</tt></li> + <li><tt>__c11_atomic_load</tt></li> + <li><tt>__c11_atomic_exchange</tt></li> + <li><tt>__c11_atomic_compare_exchange_strong</tt></li> + <li><tt>__c11_atomic_compare_exchange_weak</tt></li> + <li><tt>__c11_atomic_fetch_add</tt></li> + <li><tt>__c11_atomic_fetch_sub</tt></li> + <li><tt>__c11_atomic_fetch_and</tt></li> + <li><tt>__c11_atomic_fetch_or</tt></li> + <li><tt>__c11_atomic_fetch_xor</tt></li> +</ul> + <!-- ======================================================================= --> <h2 id="targetspecific">Target-Specific Extensions</h2> @@ -1264,6 +1650,18 @@ balance in some way.</p> <p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>, <tt>__has_attribute(ns_returns_retained)</tt>, etc.</p> +<!-- ======================================================================= --> +<h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2> +<!-- ======================================================================= --> +<h3 id="address_sanitizer">AddressSanitizer</h3> +<p> Use <code>__has_feature(address_sanitizer)</code> +to check if the code is being built with <a + href="AddressSanitizer.html">AddressSanitizer</a>. +</p> +<p>Use <tt>__attribute__((no_address_safety_analysis))</tt> on a function +declaration to specify that address safety instrumentation (e.g. +AddressSanitizer) should not be applied to that function. +</p> <!-- ======================================================================= --> <h2 id="threadsafety">Thread-Safety Annotation Checking</h2> diff --git a/docs/ObjectiveCLiterals.html b/docs/ObjectiveCLiterals.html new file mode 100644 index 0000000..63b523c --- /dev/null +++ b/docs/ObjectiveCLiterals.html @@ -0,0 +1,314 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> +<html> +<head> + <META http-equiv="Content-Type" content="text/html; charset=UTF8"> + <title>Clang Language Extensions</title> + <link type="text/css" rel="stylesheet" href="../menu.css"> + <link type="text/css" rel="stylesheet" href="../content.css"> + <style type="text/css"> + td { + vertical-align: top; + } + th { background-color: #ffddaa; } + </style> +</head> +<body> + +<!--#include virtual="../menu.html.incl"--> + +<div id="content"> + +<h1>Objective-C Literals</h1> + +<h2>Introduction</h2> + +Three new features were introduced into clang at the same time: <i>NSNumber Literals</i> provide a syntax for creating <code>NSNumber</code> from scalar literal expressions; <i>Collection Literals</i> provide a short-hand for creating arrays and dictionaries; <i>Object Subscripting</i> provides a way to use subscripting with Objective-C objects. Users of Apple compiler releases can use these features starting with the Apple LLVM Compiler 4.0. Users of open-source LLVM.org compiler releases can use these features starting with clang v3.1.<p> + +These language additions simplify common Objective-C programming patterns, make programs more concise, and improve the safety of container creation.<p> + +This document describes how the features are implemented in clang, and how to use them in your own programs.<p> + +<h2>NSNumber Literals</h2> + +The framework class <code>NSNumber</code> is used to wrap scalar values inside objects: signed and unsigned integers (<code>char</code>, <code>short</code>, <code>int</code>, <code>long</code>, <code>long long</code>), floating point numbers (<code>float</code>, <code>double</code>), and boolean values (<code>BOOL</code>, C++ <code>bool</code>). Scalar values wrapped in objects are also known as <i>boxed</i> values.<p> + +In Objective-C, any character, numeric or boolean literal prefixed with the <code>'@'</code> character will evaluate to a pointer to an <code>NSNumber</code> object initialized with that value. C's type suffixes may be used to control the size of numeric literals. + +<h3>Examples</h3> + +The following program illustrates the rules for <code>NSNumber</code> literals:<p> + +<pre> +void main(int argc, const char *argv[]) { + // character literals. + NSNumber *theLetterZ = @'Z'; // equivalent to [NSNumber numberWithChar:'Z'] + + // integral literals. + NSNumber *fortyTwo = @42; // equivalent to [NSNumber numberWithInt:42] + NSNumber *fortyTwoUnsigned = @42U; // equivalent to [NSNumber numberWithUnsignedInt:42U] + NSNumber *fortyTwoLong = @42L; // equivalent to [NSNumber numberWithLong:42L] + NSNumber *fortyTwoLongLong = @42LL; // equivalent to [NSNumber numberWithLongLong:42LL] + + // floating point literals. + NSNumber *piFloat = @3.141592654F; // equivalent to [NSNumber numberWithFloat:3.141592654F] + NSNumber *piDouble = @3.1415926535; // equivalent to [NSNumber numberWithDouble:3.1415926535] + + // BOOL literals. + NSNumber *yesNumber = @YES; // equivalent to [NSNumber numberWithBool:YES] + NSNumber *noNumber = @NO; // equivalent to [NSNumber numberWithBool:NO] + +#ifdef __cplusplus + NSNumber *trueNumber = @true; // equivalent to [NSNumber numberWithBool:(BOOL)true] + NSNumber *falseNumber = @false; // equivalent to [NSNumber numberWithBool:(BOOL)false] +#endif +} +</pre> + +<h3>Discussion</h3> + +NSNumber literals only support literal scalar values after the '@'. Consequently, @INT_MAX works, but @INT_MIN does not, because they are defined like this:<p> + +<pre> +#define INT_MAX 2147483647 /* max value for an int */ +#define INT_MIN (-2147483647-1) /* min value for an int */ +</pre> + +The definition of INT_MIN is not a simple literal, but a parenthesized expression. This is by design, but may be improved in subsequent compiler releases.<p> + +Because <code>NSNumber</code> does not currently support wrapping <code>long double</code> values, the use of a <code>long double NSNumber</code> literal (e.g. <code>@123.23L</code>) will be rejected by the compiler.<p> + +Previously, the <code>BOOL</code> type was simply a typedef for <code>signed char</code>, and <code>YES</code> and <code>NO</code> were macros that expand to <code>(BOOL)1</code> and <code>(BOOL)0</code> respectively. To support <code>@YES</code> and <code>@NO</code> expressions, these macros are now defined using new language keywords in <code><objc/objc.h></code>:<p> + +<pre> +#if __has_feature(objc_bool) +#define YES __objc_yes +#define NO __objc_no +#else +#define YES ((BOOL)1) +#define NO ((BOOL)0) +#endif +</pre> + +The compiler implicitly converts <code>__objc_yes</code> and <code>__objc_no</code> to <code>(BOOL)1</code> and <code>(BOOL)0</code>. The keywords are used to disambiguate <code>BOOL</code> and integer literals.<p> + +Objective-C++ also supports <code>@true</code> and <code>@false</code> expressions, which are equivalent to <code>@YES</code> and <code>@NO</code>. + + +<h2>Container Literals</h2> + +Objective-C now supports a new expression syntax for creating immutable array and dictionary container objects. + +<h3>Examples</h3> + +Immutable array expression:<p> + + <pre> +NSArray *array = @[ @"Hello", NSApp, [NSNumber numberWithInt:42] ]; +</pre> + +This creates an <code>NSArray</code> with 3 elements. The comma-separated sub-expressions of an array literal can be any Objective-C object pointer typed expression.<p> + +Immutable dictionary expression:<p> + +<pre> +NSDictionary *dictionary = @{ + @"name" : NSUserName(), + @"date" : [NSDate date], + @"processInfo" : [NSProcessInfo processInfo] +}; +</pre> + +This creates an <code>NSDictionary</code> with 3 key/value pairs. Value sub-expressions of a dictionary literal must be Objective-C object pointer typed, as in array literals. Key sub-expressions must be of an Objective-C object pointer type that implements the <code><NSCopying></code> protocol.<p> + +<h3>Discussion</h3> + +Neither keys nor values can have the value <code>nil</code> in containers. If the compiler can prove that a key or value is <code>nil</code> at compile time, then a warning will be emitted. Otherwise, a runtime error will occur.<p> + +Using array and dictionary literals is safer than the variadic creation forms commonly in use today. Array literal expressions expand to calls to <code>+[NSArray arrayWithObjects:count:]</code>, which validates that all objects are non-<code>nil</code>. The variadic form, <code>+[NSArray arrayWithObjects:]</code> uses <code>nil</code> as an argument list terminator, which can lead to malformed array objects. Dictionary literals are similarly created with <code>+[NSDictionary dictionaryWithObjects:forKeys:count:]</code> which validates all objects and keys, unlike <code>+[NSDictionary dictionaryWithObjectsAndKeys:]</code> which also uses a <code>nil</code> parameter as an argument list terminator.<p> + +<h2>Object Subscripting</h2> + +Objective-C object pointer values can now be used with C's subscripting operator.<p> + +<h3>Examples</h3> + +The following code demonstrates the use of object subscripting syntax with <code>NSMutableArray</code> and <code>NSMutableDictionary</code> objects:<p> + +<pre> +NSMutableArray *array = ...; +NSUInteger idx = ...; +id newObject = ...; +id oldObject = array[idx]; +array[idx] = newObject; // replace oldObject with newObject + +NSMutableDictionary *dictionary = ...; +NSString *key = ...; +oldObject = dictionary[key]; +dictionary[key] = newObject; // replace oldObject with newObject +</pre> + +The next section explains how subscripting expressions map to accessor methods.<p> + +<h3>Subscripting Methods</h3> + +Objective-C supports two kinds of subscript expressions: <i>array-style</i> subscript expressions use integer typed subscripts; <i>dictionary-style</i> subscript expressions use Objective-C object pointer typed subscripts. Each type of subscript expression is mapped to a message send using a predefined selector. The advantage of this design is flexibility: class designers are free to introduce subscripting by declaring methods or by adopting protocols. Moreover, because the method names are selected by the type of the subscript, an object can be subscripted using both array and dictionary styles. + +<h4>Array-Style Subscripting</h4> + +When the subscript operand has an integral type, the expression is rewritten to use one of two different selectors, depending on whether the element is being read or written. When an expression reads an element using an integral index, as in the following example:<p> + +<pre> +NSUInteger idx = ...; +id value = object[idx]; +</pre> + +it is translated into a call to <code>objectAtIndexedSubscript:</code><p> + +<pre> +id value = [object objectAtIndexedSubscript:idx]; +</pre> + +When an expression writes an element using an integral index:<p> + +<pre> +object[idx] = newValue; +</pre> + +it is translated to a call to <code>setObject:atIndexedSubscript:</code><p> + +<pre> +[object setObject:newValue atIndexedSubscript:idx]; +</pre> + +These message sends are then type-checked and performed just like explicit message sends. The method used for objectAtIndexedSubscript: must be declared with an argument of integral type and a return value of some Objective-C object pointer type. The method used for setObject:atIndexedSubscript: must be declared with its first argument having some Objective-C pointer type and its second argument having integral type.<p> + +The meaning of indexes is left up to the declaring class. The compiler will coerce the index to the appropriate argument type of the method it uses for type-checking. For an instance of <code>NSArray</code>, reading an element using an index outside the range <code>[0, array.count)</code> will raise an exception. For an instance of <code>NSMutableArray</code>, assigning to an element using an index within this range will replace that element, but assigning to an element using an index outside this range will raise an exception; no syntax is provided for inserting, appending, or removing elements for mutable arrays.<p> + +A class need not declare both methods in order to take advantage of this language feature. For example, the class <code>NSArray</code> declares only <code>objectAtIndexedSubscript:</code>, so that assignments to elements will fail to type-check; moreover, its subclass <code>NSMutableArray</code> declares <code>setObject:atIndexedSubscript:</code>. + +<h4>Dictionary-Style Subscripting</h4> + +When the subscript operand has an Objective-C object pointer type, the expression is rewritten to use one of two different selectors, depending on whether the element is being read from or written to. When an expression reads an element using an Objective-C object pointer subscript operand, as in the following example:<p> + +<pre> +id key = ...; +id value = object[key]; +</pre> + +it is translated into a call to the <code>objectForKeyedSubscript:</code> method:<p> + +<pre> +id value = [object objectForKeyedSubscript:key]; +</pre> + +When an expression writes an element using an Objective-C object pointer subscript:<p> + +<pre> +object[key] = newValue; +</pre> + +it is translated to a call to <code>setObject:forKeyedSubscript:</code> + +<pre> +[object setObject:newValue forKeyedSubscript:key]; +</pre> + +The behavior of <code>setObject:forKeyedSubscript:</code> is class-specific; but in general it should replace an existing value if one is already associated with a key, otherwise it should add a new value for the key. No syntax is provided for removing elements from mutable dictionaries.<p> + +<h3>Discussion</h3> + +An Objective-C subscript expression occurs when the base operand of the C subscript operator has an Objective-C object pointer type. Since this potentially collides with pointer arithmetic on the value, these expressions are only supported under the modern Objective-C runtime, which categorically forbids such arithmetic.<p> + +Currently, only subscripts of integral or Objective-C object pointer type are supported. In C++, a class type can be used if it has a single conversion function to an integral or Objective-C pointer type, in which case that conversion is applied and analysis continues as appropriate. Otherwise, the expression is ill-formed.<p> + +An Objective-C object subscript expression is always an l-value. If the expression appears on the left-hand side of a simple assignment operator (=), the element is written as described below. If the expression appears on the left-hand side of a compound assignment operator (e.g. +=), the program is ill-formed, because the result of reading an element is always an Objective-C object pointer and no binary operators are legal on such pointers. If the expression appears in any other position, the element is read as described below. It is an error to take the address of a subscript expression, or (in C++) to bind a reference to it.<p> + +Programs can use object subscripting with Objective-C object pointers of type <code>id</code>. Normal dynamic message send rules apply; the compiler must see <i>some</i> declaration of the subscripting methods, and will pick the declaration seen first.<p> + +<h2>Grammar Additions</h2> + +To support the new syntax described above, the Objective-C <code>@</code>-expression grammar has the following new productions:<p> + +<pre> +objc-at-expression : '@' (string-literal | encode-literal | selector-literal | protocol-literal | object-literal) + ; + +object-literal : ('+' | '-')? numeric-constant + | character-constant + | boolean-constant + | array-literal + | dictionary-literal + ; + +boolean-constant : '__objc_yes' | '__objc_no' | 'true' | 'false' /* boolean keywords. */ + ; + +array-literal : '[' assignment-expression-list ']' + ; + +assignment-expression-list : assignment-expression (',' assignment-expression-list)? + | /* empty */ + ; + +dictionary-literal : '{' key-value-list '}' + ; + +key-value-list : key-value-pair (',' key-value-list)? + | /* empty */ + ; + +key-value-pair : assignment-expression ':' assignment-expression + ; +</pre> + +Note: <code>@true</code> and <code>@false</code> are only supported in Objective-C++.<p> + +<h2>Availability Checks</h2> + +Programs test for the new features by using clang's __has_feature checks. Here are examples of their use:<p> + +<pre> +#if __has_feature(objc_array_literals) + // new way. + NSArray *elements = @[ @"H", @"He", @"O", @"C" ]; +#else + // old way (equivalent). + id objects[] = { @"H", @"He", @"O", @"C" }; + NSArray *elements = [NSArray arrayWithObjects:objects count:4]; +#endif + +#if __has_feature(objc_dictionary_literals) + // new way. + NSDictionary *masses = @{ @"H" : @1.0078, @"He" : @4.0026, @"O" : @15.9990, @"C" : @12.0096 }; +#else + // old way (equivalent). + id keys[] = { @"H", @"He", @"O", @"C" }; + id values[] = { [NSNumber numberWithDouble:1.0078], [NSNumber numberWithDouble:4.0026], + [NSNumber numberWithDouble:15.9990], [NSNumber numberWithDouble:12.0096] }; + NSDictionary *masses = [NSDictionary dictionaryWithObjects:objects forKeys:keys count:4]; +#endif + +#if __has_feature(objc_subscripting) + NSUInteger i, count = elements.count; + for (i = 0; i < count; ++i) { + NSString *element = elements[i]; + NSNumber *mass = masses[element]; + NSLog(@"the mass of %@ is %@", element, mass); + } +#else + NSUInteger i, count = [elements count]; + for (i = 0; i < count; ++i) { + NSString *element = [elements objectAtIndex:i]; + NSNumber *mass = [masses objectForKey:element]; + NSLog(@"the mass of %@ is %@", element, mass); + } +#endif +</pre> + +Code can use also <code>__has_feature(objc_bool)</code> to check for the availability of numeric literals support. This checks for the new <code>__objc_yes / __objc_no</code> keywords, which enable the use of <code>@YES / @NO</code> literals.<p> + +</div> +</body> +</html> diff --git a/docs/PCHInternals.html b/docs/PCHInternals.html index d46ae5c..28ce1ce 100644 --- a/docs/PCHInternals.html +++ b/docs/PCHInternals.html @@ -1,8 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>Precompiled Headers (PCH)</title> - <link type="text/css" rel="stylesheet" href="../menu.css" /> - <link type="text/css" rel="stylesheet" href="../content.css" /> + <link type="text/css" rel="stylesheet" href="../menu.css"> + <link type="text/css" rel="stylesheet" href="../content.css"> <style type="text/css"> td { vertical-align: top; @@ -155,7 +157,7 @@ without duplicating the data from the common headers for every file.</p> <h2 id="contents">Precompiled Header Contents</h2> -<img src="PCHLayout.png" align="right" alt="Precompiled header layout"> +<img src="PCHLayout.png" style="float:right" alt="Precompiled header layout"> <p>Clang's precompiled headers are organized into several different blocks, each of which contains the serialized representation of a part diff --git a/docs/PTHInternals.html b/docs/PTHInternals.html index 279d479..b15f681 100644 --- a/docs/PTHInternals.html +++ b/docs/PTHInternals.html @@ -1,8 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>Pretokenized Headers (PTH)</title> - <link type="text/css" rel="stylesheet" href="../menu.css" /> - <link type="text/css" rel="stylesheet" href="../content.css" /> + <link type="text/css" rel="stylesheet" href="../menu.css"> + <link type="text/css" rel="stylesheet" href="../content.css"> <style type="text/css"> td { vertical-align: top; diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html new file mode 100644 index 0000000..d05c4b6 --- /dev/null +++ b/docs/ReleaseNotes.html @@ -0,0 +1,193 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Clang 3.1 Release Notes</title> +<link type="text/css" rel="stylesheet" href="../menu.css"> +<link type="text/css" rel="stylesheet" href="../content.css"> +<style type="text/css"> +td { + vertical-align: top; +} +</style> +</head> +<body> + +<!--#include virtual="../menu.html.incl"--> + +<div id="content"> + +<h1>Clang 3.1 Release Notes</h1> + +<img style="float:right" src="http://llvm.org/img/DragonSmall.png" + width="136" height="136" alt="LLVM Dragon Logo"> + +<ul> + <li><a href="#intro">Introduction</a></li> + <li><a href="#whatsnew">What's New in Clang 3.1?</a> + <ul> + <li><a href="#majorfeatures">Major New Features</a></li> + <li><a href="#cchanges">C Language Changes</a></li> + <li><a href="#cxxchanges">C++ Language Changes</a></li> + <li><a href="#objcchanges">Objective-C Language Changes</a></li> + <li><a href="#apichanges">Internal API Changes</a></li> + </ul> + </li> + <li><a href="#knownproblems">Known Problems</a></li> + <li><a href="#additionalinfo">Additional Information</a></li> +</ul> + +<div class="doc_author"> + <p>Written by the <a href="http://llvm.org/">LLVM Team</a></p> +</div> + +<h1 style="color:red">These are in-progress notes for the upcoming Clang 3.1 +release.<br> +You may prefer the +<a href="http://llvm.org/releases/3.0/docs/ClangReleaseNotes.html">Clang 3.0 +Release Notes</a>.</h1> + +<!-- ======================================================================= --> +<h2 id="intro">Introduction</h2> +<!-- ======================================================================= --> + +<p>This document contains the release notes for the Clang C/C++/Objective-C +frontend, part of the LLVM Compiler Infrastructure, release 3.1. Here we +describe the status of Clang in some detail, including major improvements from +the previous release and new feature work. For the general LLVM release notes, +see <a href="http://llvm.org/docs/ReleaseNotes.html">the LLVM + documentation</a>. All LLVM releases may be downloaded from the +<a href="http://llvm.org/releases/">LLVM releases web site</a>.</p> + +<p>For more information about Clang or LLVM, including information about the +latest release, please check out the main please see the +<a href="http://clang.llvm.org">Clang Web Site</a> or the +<a href="http://llvm.org">LLVM Web Site</a>. + +<p>Note that if you are reading this file from a Subversion checkout or the main +Clang web page, this document applies to the <i>next</i> release, not the +current one. To see the release notes for a specific release, please see the +<a href="http://llvm.org/releases/">releases page</a>.</p> + +<!-- ======================================================================= --> +<h2 id="whatsnew">What's New in Clang 3.1?</h2> +<!-- ======================================================================= --> + +<p>Some of the major new features and improvements to Clang are listed here. +Generic improvements to Clang as a whole or two its underlying infrastructure +are described first, followed by language-specific sections with improvements to +Clang's support for those languages.</p> + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="majorfeatures">Major New Features</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +<h4 id="majorfeature1">Feature 1</h4> +... + +<h4 id="diagnostics">New and better diagnostics</h4> + +<p>New: <code>-Wdangling-else</code>, <code>-Wstrncat-size</code>, ...</p> + +<p>Improved: <code>-Wformat</code>, <code>-Wempty-body</code>, +<code>-Wliteral-conversion</code>, ...</p> + +<h4 id="tooling">Tooling</h4> +<!-- FIXME: add a link to the tooling documentation once that's written. --> +<p>Added an API to enable clang-based standalone tools, including initial build +system integration.</p> + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="cchanges">C Language Changes in Clang</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +<h4 id="c11changes">C11 Feature Support</h4> + +<p>Clang 3.1 adds support for anonymous structs and anonymous unions, added in +the latest ISO C standard. Use <code>-std=c11</code> or <code>-std=gnu11</code> +to enable support for the new language standard. The new C11 features are +backwards-compatible and are available as an extension in all language +modes.</p> + +<p>All warning and language selection flags which previously accepted +<code>c1x</code> have been updated to accept <code>c11</code>. The old +<code>c1x</code> forms have been removed. + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="cxxchanges">C++ Language Changes in Clang</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +<h4 id="cxx11changes">C++11 Feature Support</h4> +<p>Clang 3.1 adds support for +<a href="http://clang.llvm.org/cxx_status.html#cxx11">more of the language +features</a> added in the latest ISO C++ standard, +<a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=50372">C++ 2011</a>. +Use <code>-std=c++11</code> or <code>-std=gnu++11</code> to enable support for +these features. In addition to the features supported by Clang 3.0, the +following are now considered to be of production quality: +<ul> + <li>Generalized constant expressions</li> + <li>Lambda expressions</li> + <li>Generalized initializers</li> + <li>Unrestricted unions</li> + <li>User-defined literals</li> + <li>Forward-declared enumerations</li> + <li>Atomics (both libc++'s and libstdc++4.7's <tt><atomic></tt> are + supported)</li> +</ul> + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="objcchanges">Objective-C Language Changes in Clang</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +Clang 3.1 introduces several new Objective-C language features and improvements. + +<h4 id="objcwformat">Format string checking for NSString literals</h4> + +<code>-Wformat</code> now checks <code>@"nsstring literals"</code>. + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="apichanges">Internal API Changes</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +These are major API changes that have happened since the 3.0 release of Clang. +If upgrading an external codebase that uses Clang as a library, this section +should help get you past the largest hurdles of upgrading. + +<h4 id="api1">API change 1</h4> +... + +<!-- ======================================================================= --> +<h2 id="knownproblems">Significant Known Problems</h2> +<!-- ======================================================================= --> + +<!-- ======================================================================= --> +<h2 id="additionalinfo">Additional Information</h2> +<!-- ======================================================================= --> + +<p>A wide variety of additional information is available on the +<a href="http://clang.llvm.org/">Clang web page</a>. The web page contains +versions of the API documentation which are up-to-date with the Subversion +version of the source code. You can access versions of these documents specific +to this release by going into the "<tt>clang/doc/</tt>" directory in the Clang +tree.</p> + +<p>If you have any questions or comments about Clang, please feel free to +contact us via the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev"> +mailing list</a>.</p> + + +<!-- ======================================================================= --> +<!-- Likely 3.1 release notes --> +<!-- ======================================================================= --> +<!-- +This is just a section to hold things that have already gotten started and +should likely pick up proper release notes in 3.1. + +- C1X and C++11 atomics infrastructure and support +- CUDA support? + +--> + +</div> +</body> +</html> diff --git a/docs/UsersManual.html b/docs/UsersManual.html index 9d79819..b33ed61 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -1,8 +1,10 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>Clang Compiler User's Manual</title> -<link type="text/css" rel="stylesheet" href="../menu.css" /> -<link type="text/css" rel="stylesheet" href="../content.css" /> +<link type="text/css" rel="stylesheet" href="../menu.css"> +<link type="text/css" rel="stylesheet" href="../content.css"> <style type="text/css"> td { vertical-align: top; @@ -28,6 +30,8 @@ td { <ul> <li><a href="#cl_diagnostics">Options to Control Error and Warning Messages</a></li> + <li><a href="#cl_crash_diagnostics">Options to Control Clang Crash + Diagnostics</a></li> </ul> </li> <li><a href="#general_features">Language and Target-Independent Features</a> @@ -56,6 +60,11 @@ td { <li><a href="#c_ms">Microsoft extensions</a></li> </ul> </li> +<li><a href="#cxx">C++ Language Features</a> + <ul> + <li><a href="#cxx_implimits">Controlling implementation limits</a></li> + </ul> +</li> <li><a href="#target_features">Target-Specific Features and Limitations</a> <ul> <li><a href="#target_arch">CPU Architectures Features and Limitations</a> @@ -92,7 +101,7 @@ Web Site</a> or the <a href="http://llvm.org">LLVM Web Site</a>.</p> 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 <a href="InternalsManual.html">the Clang Internals Manual</a>. If you are -interested in the <a href="http://clang.llvm.org/StaticAnalysis.html">Clang +interested in the <a href="http://clang-analyzer.llvm.org">Clang Static Analyzer</a>, please see its web page.</p> <p>Clang is designed to support the C family of programming languages, which @@ -106,7 +115,7 @@ corresponding language specific section:</p> (C89+AMD1), ISO C99 (+TC1, TC2, TC3). </li> <li><a href="#objc">Objective-C Language</a>: ObjC 1, ObjC 2, ObjC 2.1, plus variants depending on base language.</li> -<li><a href="#cxx">C++ Language Features</a></li> +<li><a href="#cxx">C++ Language</a></li> <li><a href="#objcxx">Objective C++ Language</a></li> </ul> @@ -258,10 +267,10 @@ when this is enabled, Clang will print something like: 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> + <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b> #endif bad - <font color="green">^</font> - <font color="green">//</font> + <span style="color:green">^</span> + <span style="color:green">//</span> </pre> <p>When this is disabled, Clang will just print:</p> @@ -300,8 +309,7 @@ Changes diagnostic output format to better match IDEs and command line tools.</d <dt id="opt_fdiagnostics-show-name"><b>-f[no-]diagnostics-show-name</b>: Enable the display of the diagnostic name.</dt> <dd>This option, which defaults to off, controls whether or not -Clang prints the associated name.</dd> -<br> +Clang prints the associated name.<p></p></dd> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <dt id="opt_fdiagnostics-show-option"><b>-f[no-]diagnostics-show-option</b>: Enable <tt>[-Woption]</tt> information in diagnostic line.</dt> @@ -409,7 +417,6 @@ quotes(as "\"") and non-printable characters (as octal </dl> - <!-- ===================================================== --> @@ -480,7 +487,7 @@ constructor. For example: }; void foo(const NonCopyable&); void bar() { - foo(NonCopyable()); // Disallowed in C++98; allowed in C++0x. + foo(NonCopyable()); // Disallowed in C++98; allowed in C++11. } </pre> <pre> @@ -490,7 +497,7 @@ constructor. For example: }; void foo(const NonCopyable2&); void bar() { - foo(NonCopyable2()); // Disallowed in C++98; allowed in C++0x. + foo(NonCopyable2()); // Disallowed in C++98; allowed in C++11. } </pre> @@ -503,6 +510,27 @@ off.</p> </dl> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="cl_crash_diagnostics">Options to Control Clang Crash Diagnostics</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +<p>As unbelievable as it may sound, Clang does crash from time to time. +Generally, this only occurs to those living on the +<a href="http://llvm.org/releases/download.html#svn">bleeding edge</a>. Clang +goes to great lengths to assist you in filing a bug report. Specifically, Clang +generates preprocessed source file(s) and associated run script(s) upon a +crash. These files should be attached to a bug report to ease reproducibility +of the failure. Below are the command line options to control the crash +diagnostics. +</p> + +<p><b>-fno-crash-diagnostics</b>: Disable auto-generation of preprocessed +source files during a clang crash.</p> + +<p>The -fno-crash-diagnostics flag can be helpful for speeding the process of +generating a delta reduced test case.</p> + + <!-- ======================================================================= --> <h2 id="general_features">Language and Target-Independent Features</h2> <!-- ======================================================================= --> @@ -529,8 +557,6 @@ it:</p> <li>A categorization of the diagnostic as a note, warning, error, or fatal error.</li> <li>A text string that describes what the problem is.</li> -<li>An option that indicates whether to print the diagnostic name [<a - href="#opt_fdiagnostics-show-name">-fdiagnostics-show-name</a>].</li> <li>An option that indicates how to control the diagnostic (for diagnostics that support it) [<a href="#opt_fdiagnostics-show-option">-fdiagnostics-show-option</a>].</li> @@ -669,7 +695,7 @@ 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 of which can already be done using <a -href="analyzer_annotations">annotations</a>).</li> +href="#analyzer_annotations">annotations</a>).</li> </ul> @@ -804,6 +830,14 @@ The checks are: </ul> </dd> +<dt id="opt_faddress-sanitizer"><b>-f[no-]address-sanitizer</b>: +Turn on <a href="AddressSanitizer.html">AddressSanitizer</a>, +a memory error detector. + +<dt id="opt_fthread-sanitizer"><b>-f[no-]thread-sanitizer</b>: +Turn on ThreadSanitizer, an <em>experimental</em> data race detector. +Not ready for widespread use. + <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 @@ -951,10 +985,6 @@ a structure).</li> 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.</li> -<li>clang does not support multiple alternative constraints in inline asm; this -is an extremely obscure feature which would be complicated to implement -correctly.</li> - <li>clang does not support __builtin_apply and friends; this extension is extremely obscure and difficult to implement reliably.</li> @@ -988,6 +1018,25 @@ definition.</li> </ul> <!-- ======================================================================= --> +<h2 id="cxx">C++ Language Features</h2> +<!-- ======================================================================= --> + +<p>clang fully implements all of standard C++98 except for exported templates +(which were removed in C++11), and +<a href="http://clang.llvm.org/cxx_status.html">many C++11 features</a> are also +implemented.</p> + +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> +<h3 id="cxx_implimits">Controlling implementation limits</h3> +<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> + +<p><b>-fconstexpr-depth=N</b>: Sets the limit for recursive constexpr function +invocations to N. The default is 512.</p> + +<p><b>-ftemplate-depth=N</b>: Sets the limit for recursively nested template +instantiations to N. The default is 1024.</p> + +<!-- ======================================================================= --> <h2 id="target_features">Target-Specific Features and Limitations</h2> <!-- ======================================================================= --> @@ -1066,7 +1115,7 @@ Clang assumes directories as below;</p> <li><tt>C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</tt></li> </ul> -<p>On MSYS, a few tests might fail. It is due to <a href="http://llvm.org/bugs/show_bug.cgi?id=8520">Bug 8520</a> and is fixed in <a href="http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20110314/118106.html">LLVM's r127724</a>.</p> +<p>On MSYS, a few tests might fail.</p> <h5>MinGW-w64</h5> diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index 7f3292c..ed9ffcb 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -39,7 +39,7 @@ OUTPUT_DIRECTORY = @abs_builddir@/doxygen # source files, where putting all generated files in the same directory would # otherwise cause performance problems for the file system. -CREATE_SUBDIRS = YES +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 diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod index 964b143..8f61568 100644 --- a/docs/tools/clang.pod +++ b/docs/tools/clang.pod @@ -465,7 +465,7 @@ for include files. =item B<-nostdlibinc> Do not search the standard system directories for include files, but do search -compiler builting include directories. +compiler builtin include directories. =item B<-nobuiltininc> |
