diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AutomaticReferenceCounting.html | 83 | ||||
| -rw-r--r-- | docs/InternalsManual.html | 223 | ||||
| -rw-r--r-- | docs/LanguageExtensions.html | 392 | ||||
| -rw-r--r-- | docs/UsersManual.html | 37 | ||||
| -rw-r--r-- | docs/doxygen.cfg.in | 2 | ||||
| -rw-r--r-- | docs/doxygen.css | 30 | ||||
| -rw-r--r-- | docs/tools/clang.pod | 8 |
7 files changed, 729 insertions, 46 deletions
diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html index 5090fa2b7952..bc784578e4cf 100644 --- a/docs/AutomaticReferenceCounting.html +++ b/docs/AutomaticReferenceCounting.html @@ -1315,6 +1315,39 @@ and only if the value is not demonstrably already retained.</p> <p>The complete optimization rules are quite complicated, but it would still be useful to document them here.</p> +<div id="optimization.precise"> +<h1>Precise lifetime semantics</h1> + +<p>In general, ARC maintains an invariant that a retainable object +pointer held in a <tt>__strong</tt> object will be retained for the +full formal lifetime of the object. Objects subject to this invariant +have <span class="term">precise lifetime semantics</span>.</p> + +<p>By default, local variables of automatic storage duration do not +have precise lifetime semantics. Such objects are simply strong +references which hold values of retainable object pointer type, and +these values are still fully subject to the optimizations on values +under local control.</p> + +<div class="rationale"><p>Rationale: applying these precise-lifetime +semantics strictly would be prohibitive. Many useful optimizations +that might theoretically decrease the lifetime of an object would be +rendered impossible. Essentially, it promises too much.</p></div> + +<p>A local variable of retainable object owner type and automatic +storage duration may be annotated with the <tt>objc_precise_lifetime</tt> +attribute to indicate that it should be considered to be an object +with precise lifetime semantics.</p> + +<div class="rationale"><p>Rationale: nonetheless, it is sometimes +useful to be able to force an object to be released at a precise time, +even if that object does not appear to be used. This is likely to be +uncommon enough that the syntactic weight of explicitly requesting +these semantics will not be burdensome, and may even make the code +clearer.</p></div> + +</div> <!-- optimization.precise --> + </div> <div id="misc"> @@ -1562,6 +1595,56 @@ from exceptions.</p></div> </div> <!-- misc.exceptions --> +<div id="misc.interior"> +<h1>Interior pointers</h1> + +<p>An Objective-C method returning a non-retainable pointer may be +annotated with the <tt>objc_returns_inner_pointer</tt> attribute to +indicate that it returns a handle to the internal data of an object, +and that this reference will be invalidated if the object is +destroyed. When such a message is sent to an object, the object's +lifetime will be extended until at least the earliest of:</p> + +<ul> +<li>the last use of the returned pointer, or any pointer derived from +it, in the calling function or</li> +<li>the autorelease pool is restored to a previous state.</li> +</ul> + +<div class="rationale"><p>Rationale: not all memory and resources are +managed with reference counts; it is common for objects to manage +private resources in their own, private way. Typically these +resources are completely encapsulated within the object, but some +classes offer their users direct access for efficiency. If ARC is not +aware of methods that return such <q>interior</q> pointers, its +optimizations can cause the owning object to be reclaimed too soon. +This attribute informs ARC that it must tread lightly.</p> + +<p>The extension rules are somewhat intentionally vague. The +autorelease pool limit is there to permit a simple implementation to +simply retain and autorelease the receiver. The other limit permits +some amount of optimization. The phrase <q>derived from</q> is +intended to encompass the results both of pointer transformations, +such as casts and arithmetic, and of loading from such derived +pointers; furthermore, it applies whether or not such derivations are +applied directly in the calling code or by other utility code (for +example, the C library routine <tt>strchr</tt>). However, the +implementation never need account for uses after a return from the +code which calls the method returning an interior pointer.</p></div> + +<p>As an exception, no extension is required if the receiver is loaded +directly from a <tt>__strong</tt> object +with <a href="#optimization.precise">precise lifetime semantics</a>.</p> + +<div class="rationale"><p>Rationale: implicit autoreleases carry the +risk of significantly inflating memory use, so it's important to +provide users a way of avoiding these autoreleases. Tying this to +precise lifetime semantics is ideal, as for local variables this +requires a very explicit annotation, which allows ARC to trust the +user with good cheer.</p></div> + +</div> <!-- misc.interior --> + </div> <!-- misc --> <div id="runtime"> diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 5d97609373b7..54f01fca0e7a 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -71,6 +71,7 @@ td { <li><a href="#Howtos">Howto guides</a> <ul> <li><a href="#AddingAttributes">How to add an attribute</a></li> + <li><a href="#AddingExprStmt">How to add a new expression or statement</a></li> </ul> </li> </ul> @@ -1785,6 +1786,228 @@ Check for the attribute's presence using <tt>Decl::getAttr<YourAttr>()</tt>.< <p>Update the <a href="LanguageExtensions.html">Clang Language Extensions</a> document to describe your new attribute.</p> +<!-- ======================================================================= --> +<h3 id="AddingExprStmt">How to add an expression or statement</h3> +<!-- ======================================================================= --> + +<p>Expressions and statements are one of the most fundamental constructs within a +compiler, because they interact with many different parts of the AST, +semantic analysis, and IR generation. Therefore, adding a new +expression or statement kind into Clang requires some care. The following list +details the various places in Clang where an expression or statement needs to be +introduced, along with patterns to follow to ensure that the new +expression or statement works well across all of the C languages. We +focus on expressions, but statements are similar.</p> + +<ol> + <li>Introduce parsing actions into the parser. Recursive-descent + parsing is mostly self-explanatory, but there are a few things that + are worth keeping in mind: + <ul> + <li>Keep as much source location information as possible! You'll + want it later to produce great diagnostics and support Clang's + various features that map between source code and the AST.</li> + <li>Write tests for all of the "bad" parsing cases, to make sure + your recovery is good. If you have matched delimiters (e.g., + parentheses, square brackets, etc.), use + <tt>Parser::BalancedDelimiterTracker</tt> to give nice diagnostics when + things go wrong.</li> + </ul> + </li> + + <li>Introduce semantic analysis actions into <tt>Sema</tt>. Semantic + analysis should always involve two functions: an <tt>ActOnXXX</tt> + function that will be called directly from the parser, and a + <tt>BuildXXX</tt> function that performs the actual semantic + analysis and will (eventually!) build the AST node. It's fairly + common for the <tt>ActOnCXX</tt> function to do very little (often + just some minor translation from the parser's representation to + <tt>Sema</tt>'s representation of the same thing), but the separation + is still important: C++ template instantiation, for example, + should always call the <tt>BuildXXX</tt> variant. Several notes on + semantic analysis before we get into construction of the AST: + <ul> + <li>Your expression probably involves some types and some + subexpressions. Make sure to fully check that those types, and the + types of those subexpressions, meet your expectations. Add + implicit conversions where necessary to make sure that all of the + types line up exactly the way you want them. Write extensive tests + to check that you're getting good diagnostics for mistakes and + that you can use various forms of subexpressions with your + expression.</li> + <li>When type-checking a type or subexpression, make sure to first + check whether the type is "dependent" + (<tt>Type::isDependentType()</tt>) or whether a subexpression is + type-dependent (<tt>Expr::isTypeDependent()</tt>). If any of these + return true, then you're inside a template and you can't do much + type-checking now. That's normal, and your AST node (when you get + there) will have to deal with this case. At this point, you can + write tests that use your expression within templates, but don't + try to instantiate the templates.</li> + <li>For each subexpression, be sure to call + <tt>Sema::CheckPlaceholderExpr()</tt> to deal with "weird" + expressions that don't behave well as subexpressions. Then, + determine whether you need to perform + lvalue-to-rvalue conversions + (<tt>Sema::DefaultLvalueConversion</tt>e) or + the usual unary conversions + (<tt>Sema::UsualUnaryConversions</tt>), for places where the + subexpression is producing a value you intend to use.</li> + <li>Your <tt>BuildXXX</tt> function will probably just return + <tt>ExprError()</tt> at this point, since you don't have an AST. + That's perfectly fine, and shouldn't impact your testing.</li> + </ul> + </li> + + <li>Introduce an AST node for your new expression. This starts with + declaring the node in <tt>include/Basic/StmtNodes.td</tt> and + creating a new class for your expression in the appropriate + <tt>include/AST/Expr*.h</tt> header. It's best to look at the class + for a similar expression to get ideas, and there are some specific + things to watch for: + <ul> + <li>If you need to allocate memory, use the <tt>ASTContext</tt> + allocator to allocate memory. Never use raw <tt>malloc</tt> or + <tt>new</tt>, and never hold any resources in an AST node, because + the destructor of an AST node is never called.</li> + + <li>Make sure that <tt>getSourceRange()</tt> covers the exact + source range of your expression. This is needed for diagnostics + and for IDE support.</li> + + <li>Make sure that <tt>children()</tt> visits all of the + subexpressions. This is important for a number of features (e.g., IDE + support, C++ variadic templates). If you have sub-types, you'll + also need to visit those sub-types in the + <tt>RecursiveASTVisitor</tt>.</li> + + <li>Add printing support (<tt>StmtPrinter.cpp</tt>) and dumping + support (<tt>StmtDumper.cpp</tt>) for your expression.</li> + + <li>Add profiling support (<tt>StmtProfile.cpp</tt>) for your AST + node, noting the distinguishing (non-source location) + characteristics of an instance of your expression. Omitting this + step will lead to hard-to-diagnose failures regarding matching of + template declarations.</li> + </ul> + </li> + + <li>Teach semantic analysis to build your AST node! At this point, + you can wire up your <tt>Sema::BuildXXX</tt> function to actually + create your AST. A few things to check at this point: + <ul> + <li>If your expression can construct a new C++ class or return a + new Objective-C object, be sure to update and then call + <tt>Sema::MaybeBindToTemporary</tt> for your just-created AST node + to be sure that the object gets properly destructed. An easy way + to test this is to return a C++ class with a private destructor: + semantic analysis should flag an error here with the attempt to + call the destructor.</li> + <li>Inspect the generated AST by printing it using <tt>clang -cc1 + -ast-print</tt>, to make sure you're capturing all of the + important information about how the AST was written.</li> + <li>Inspect the generated AST under <tt>clang -cc1 -ast-dump</tt> + to verify that all of the types in the generated AST line up the + way you want them. Remember that clients of the AST should never + have to "think" to understand what's going on. For example, all + implicit conversions should show up explicitly in the AST.</li> + <li>Write tests that use your expression as a subexpression of + other, well-known expressions. Can you call a function using your + expression as an argument? Can you use the ternary operator?</li> + </ul> + </li> + + <li>Teach code generation to create IR to your AST node. This step + is the first (and only) that requires knowledge of LLVM IR. There + are several things to keep in mind: + <ul> + <li>Code generation is separated into scalar/aggregate/complex and + lvalue/rvalue paths, depending on what kind of result your + expression produces. On occasion, this requires some careful + factoring of code to avoid duplication.</li> + + <li><tt>CodeGenFunction</tt> contains functions + <tt>ConvertType</tt> and <tt>ConvertTypeForMem</tt> that convert + Clang's types (<tt>clang::Type*</tt> or <tt>clang::QualType</tt>) + to LLVM types. + Use the former for values, and the later for memory locations: + test with the C++ "bool" type to check this. If you find + that you are having to use LLVM bitcasts to make + the subexpressions of your expression have the type that your + expression expects, STOP! Go fix semantic analysis and the AST so + that you don't need these bitcasts.</li> + + <li>The <tt>CodeGenFunction</tt> class has a number of helper + functions to make certain operations easy, such as generating code + to produce an lvalue or an rvalue, or to initialize a memory + location with a given value. Prefer to use these functions rather + than directly writing loads and stores, because these functions + take care of some of the tricky details for you (e.g., for + exceptions).</li> + + <li>If your expression requires some special behavior in the event + of an exception, look at the <tt>push*Cleanup</tt> functions in + <tt>CodeGenFunction</tt> to introduce a cleanup. You shouldn't + have to deal with exception-handling directly.</li> + + <li>Testing is extremely important in IR generation. Use <tt>clang + -cc1 -emit-llvm</tt> and <a + href="http://llvm.org/cmds/FileCheck.html">FileCheck</a> to verify + that you're generating the right IR.</li> + </ul> + </li> + + <li>Teach template instantiation how to cope with your AST + node, which requires some fairly simple code: + <ul> + <li>Make sure that your expression's constructor properly + computes the flags for type dependence (i.e., the type your + expression produces can change from one instantiation to the + next), value dependence (i.e., the constant value your expression + produces can change from one instantiation to the next), + instantiation dependence (i.e., a template parameter occurs + anywhere in your expression), and whether your expression contains + a parameter pack (for variadic templates). Often, computing these + flags just means combining the results from the various types and + subexpressions.</li> + + <li>Add <tt>TransformXXX</tt> and <tt>RebuildXXX</tt> functions to + the + <tt>TreeTransform</tt> class template in <tt>Sema</tt>. + <tt>TransformXXX</tt> should (recursively) transform all of the + subexpressions and types + within your expression, using <tt>getDerived().TransformYYY</tt>. + If all of the subexpressions and types transform without error, it + will then call the <tt>RebuildXXX</tt> function, which will in + turn call <tt>getSema().BuildXXX</tt> to perform semantic analysis + and build your expression.</li> + + <li>To test template instantiation, take those tests you wrote to + make sure that you were type checking with type-dependent + expressions and dependent types (from step #2) and instantiate + those templates with various types, some of which type-check and + some that don't, and test the error messages in each case.</li> + </ul> + </li> + + <li>There are some "extras" that make other features work better. + It's worth handling these extras to give your expression complete + integration into Clang: + <ul> + <li>Add code completion support for your expression in + <tt>SemaCodeComplete.cpp</tt>.</li> + + <li>If your expression has types in it, or has any "interesting" + features other than subexpressions, extend libclang's + <tt>CursorVisitor</tt> to provide proper visitation for your + expression, enabling various IDE features such as syntax + highlighting, cross-referencing, and so on. The + <tt>c-index-test</tt> helper program can be used to test these + features.</li> + </ul> + </li> +</ol> + </div> </body> </html> diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html index 7ee8f010a32b..c4a8047f1f48 100644 --- a/docs/LanguageExtensions.html +++ b/docs/LanguageExtensions.html @@ -4,7 +4,7 @@ <html> <head> <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> - <title>Clang LanguageExtensions</title> + <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"> @@ -38,29 +38,41 @@ <ul> <li><a href="#cxx0x">C++0x</a> <ul> - <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li> - <li><a href="#cxx_access_control_sfinae">C++0x SFINAE includes access control</a></li> + <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_variadic_templates">C++0x variadic templates</a></li> - <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li> - <li><a href="#cxx_strong_enums">C++0x strongly-typed enumerations</a></li> + <li><a href="#cxx_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_noexcept">C++0x noexcept specification</a></li> - </ul></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> <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> @@ -71,9 +83,11 @@ <ul> <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> </ul> </li> <li><a href="#overloading-in-c">Function Overloading in C</a></li> +<li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li> <li><a href="#builtins">Builtin Functions</a> <ul> <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li> @@ -87,6 +101,27 @@ </ul> </li> <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li> +<li><a href="#threadsafety">Thread Safety Annotation Checking</a></li> + <ul> + <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li> + <li><a href="#ts_lockable"><tt>lockable</tt></a></li> + <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li> + <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li> + <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li> + <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li> + <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li> + <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li> + <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li> + <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li> + <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li> + <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li> + <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li> + <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li> + <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li> + <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li> + <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> </ul> <!-- ======================================================================= --> @@ -267,6 +302,23 @@ and will issue a warning if used in the top-level compilation file. A warning will also be issued if an absolute path is used in the file argument.</p> + +<!-- ======================================================================= --> +<h3><a name="__has_warning">__has_warning</a></h3> +<!-- ======================================================================= --> + +<p>This function-like macro takes a string literal that represents a command + line option for a warning and returns true if that is a valid warning + option.</p> + +<blockquote> +<pre> +#if __has_warning("-Wformat") +... +#endif +</pre> +</blockquote> + <!-- ======================================================================= --> <h2 id="builtinmacros">Builtin Macros</h2> <!-- ======================================================================= --> @@ -416,12 +468,6 @@ noted.</p> C++0x standard. As a result, all these features are enabled with the <tt>-std=c++0x</tt> option when compiling C++ code.</p> -<h4 id="cxx_decltype">C++0x <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> - <h4 id="cxx_access_control_sfinae">C++0x 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> @@ -432,12 +478,30 @@ with the <tt>-std=c++0x</tt> option when compiling C++ code.</p> <tt>__has_extension(cxx_alias_templates)</tt> to determine if support for C++0x's alias declarations and alias templates is enabled.</p> +<h4 id="cxx_alignas">C++0x 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> <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> +<h4 id="cxx_constexpr">C++0x 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> + +<h4 id="cxx_decltype">C++0x <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> + <h4 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h4> <p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or @@ -455,11 +519,46 @@ support for delegating constructors is enabled.</p> <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> +<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> + +<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> + +<h4 id="cxx_implicit_moves">C++0x 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> + +<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> + +<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> <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. Clang does not currently implement this feature.</p> + +<h4 id="cxx_noexcept">C++0x 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> + +<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> @@ -486,6 +585,9 @@ is enabled.</p> <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_rvalue_references">C++0x rvalue references</h4> <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or @@ -505,17 +607,11 @@ compile-time assertions using <tt>static_assert</tt> is enabled.</p> 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_variadic_templates">C++0x 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> - -<h4 id="cxx_inline_namespaces">C++0x inline namespaces</h4> +<h4 id="cxx_strong_enums">C++0x strongly typed enumerations</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> +<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> @@ -523,17 +619,23 @@ inline namespaces is enabled.</p> <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_noexcept">C++0x noexcept</h4> +<h4 id="cxx_unicode_literals">C++0x Unicode string literals</h4> +<p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if +support for Unicode string literals is enabled.</p> -<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_unrestricted_unions">C++0x unrestricted unions</h4> -<h4 id="cxx_strong_enums">C++0x strongly typed enumerations</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_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_user_literals">C++0x 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> + +<h4 id="cxx_variadic_templates">C++0x 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> @@ -541,6 +643,12 @@ strongly typed, scoped enumerations is enabled.</p> C1X standard. As a result, all these features are enabled with the <tt>-std=c1x</tt> option when compiling C code.</p> +<h4 id="c_alignas">C1X 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> <p>Use <tt>__has_feature(c_generic_selections)</tt> or @@ -599,6 +707,7 @@ 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> </ul> <!-- ======================================================================= --> @@ -648,7 +757,19 @@ related result type. Similarly, the type of the expression <code>init</code> has a related result type and its receiver is known to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p> -<p>To determine whether a method has a related result type, the first +<p>A method with a related result type can be declared by using the +type <tt>instancetype</tt> as its result type. <tt>instancetype</tt> +is a contextual keyword that is only permitted in the result type of +an Objective-C method, e.g.</p> + +<pre> +@interface A ++ (<b>instancetype</b>)constructAnA; +@end +</pre> + +<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 type is compatible with the type of its class and if</p> @@ -677,8 +798,11 @@ with the subclass type. For example:</p> <p>Related result types only affect the type of a message send or property access via the given method. In all other respects, a method -with a related result type is treated the same way as method without a -related result type.</p> +with a related result type is treated the same way as method that +returns <tt>id</tt>.</p> + +<p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether +the <tt>instancetype</tt> contextual keyword is available.</p> <!-- ======================================================================= --> <h2 id="objc_arc">Automatic reference counting </h2> @@ -687,6 +811,24 @@ related result type.</p> <p>Clang provides support for <a href="AutomaticReferenceCounting.html">automated reference counting</a> in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: <code>__has_feature(objc_arc)</code> indicates the availability of automated reference counting in general, while <code>__has_feature(objc_arc_weak)</code> indicates that automated reference counting also includes support for <code>__weak</code> pointers to Objective-C objects.</p> <!-- ======================================================================= --> +<h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2> +<!-- ======================================================================= --> + +<p>Clang provides support for C++0x enumerations with a fixed +underlying type within Objective-C. For example, one can write an +enumeration type as:</p> + +<pre> +typedef enum : unsigned char { Red, Green, Blue } Color; +</pre> + +<p>This specifies that the underlying type, which is used to store the +enumeration value, is <tt>unsigned char</tt>.</p> + +<p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether +support for fixed underlying types is available in Objective-C.</p> + +<!-- ======================================================================= --> <h2 id="overloading-in-c">Function Overloading in C</h2> <!-- ======================================================================= --> @@ -786,6 +928,41 @@ caveats to this use of name mangling:</p> <p>Query for this feature with __has_extension(attribute_overloadable).</p> +<!-- ======================================================================= --> +<h2 id="complex-list-init">Initializer lists for complex numbers in C</h2> +<!-- ======================================================================= --> + +<p>clang supports an extension which allows the following in C:</p> + +<blockquote> +<pre> +#include <math.h> +#include <complex.h> +complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) +</pre> +</blockquote> + +<p>This construct is useful because there is no way to separately +initialize the real and imaginary parts of a complex variable in +standard C, given that clang does not support <code>_Imaginary</code>. +(clang also supports the <code>__real__</code> and <code>__imag__</code> +extensions from gcc, which help in some cases, but are not usable in +static initializers.) + +<p>Note that this extension does not allow eliding the braces; the +meaning of the following two lines is different:</p> + +<blockquote> +<pre> +complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) +complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) +</pre> +</blockquote> + +<p>This extension also works in C++ mode, as far as that goes, but does not + apply to the C++ <code>std::complex</code>. (In C++11, list + initialization allows the same syntax to be used with + <code>std::complex</code> with the same meaning.) <!-- ======================================================================= --> <h2 id="builtins">Builtin Functions</h2> @@ -1087,6 +1264,149 @@ 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="threadsafety">Thread-Safety Annotation Checking</h2> +<!-- ======================================================================= --> + +<p>Clang supports additional attributes for checking basic locking policies in +multithreaded programs. +Clang currently parses the following list of attributes, although +<b>the implementation for these annotations is currently in development.</b> +For more details, see the +<a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>. +</p> + +<h4 id="ts_noanal">no_thread_safety_analysis</h4> + +<p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function +declaration to specify that the thread safety analysis should not be run on that +function. This attribute provides an escape hatch (e.g. for situations when it +is difficult to annotate the locking policy). </p> + +<h4 id="ts_lockable">lockable</h4> + +<p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify +that it has a lockable type (e.g. a Mutex class). This annotation is primarily +used to check consistency.</p> + +<h4 id="ts_scopedlockable">scoped_lockable</h4> + +<p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to +specify that it has a "scoped" lockable type. Objects of this type will acquire +the lock upon construction and release it upon going out of scope. + This annotation is primarily used to check +consistency.</p> + +<h4 id="ts_guardedvar">guarded_var</h4> + +<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to +specify that the variable must be accessed while holding some lock.</p> + +<h4 id="ts_ptguardedvar">pt_guarded_var</h4> + +<p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to +specify that the pointer must be dereferenced while holding some lock.</p> + +<h4 id="ts_guardedby">guarded_by(l)</h4> + +<p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to +specify that the variable must be accessed while holding lock <tt>l</tt>.</p> + +<h4 id="ts_ptguardedby">pt_guarded_by(l)</h4> + +<p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to +specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p> + +<h4 id="ts_acquiredbefore">acquired_before(...)</h4> + +<p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration +of a lockable variable to specify that the lock must be acquired before all +attribute arguments. Arguments must be lockable type, and there must be at +least one argument.</p> + +<h4 id="ts_acquiredafter">acquired_after(...)</h4> + +<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration +of a lockable variable to specify that the lock must be acquired after all +attribute arguments. Arguments must be lockable type, and there must be at +least one argument.</p> + +<h4 id="ts_elf">exclusive_lock_function(...)</h4> + +<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function +declaration to specify that the function acquires all listed locks +exclusively. This attribute takes zero or more arguments: either of lockable +type or integers indexing into function parameters of lockable type. If no +arguments are given, the acquired lock is implicitly <tt>this</tt> of the +enclosing object.</p> + +<h4 id="ts_slf">shared_lock_function(...)</h4> + +<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function +declaration to specify that the function acquires all listed locks, although + the locks may be shared (e.g. read locks). This attribute takes zero or more +arguments: either of lockable type or integers indexing into function +parameters of lockable type. If no arguments are given, the acquired lock is +implicitly <tt>this</tt> of the enclosing object.</p> + +<h4 id="ts_etf">exclusive_trylock_function(...)</h4> + +<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function +declaration to specify that the function will try (without blocking) to acquire +all listed locks exclusively. This attribute takes one or more arguments. The +first argument is an integer or boolean value specifying the return value of a +successful lock acquisition. The remaining arugments are either of lockable type +or integers indexing into function parameters of lockable type. If only one +argument is given, the acquired lock is implicitly <tt>this</tt> of the +enclosing object.</p> + +<h4 id="ts_stf">shared_trylock_function(...)</h4> + +<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function +declaration to specify that the function will try (without blocking) to acquire +all listed locks, although the locks may be shared (e.g. read locks). This +attribute takes one or more arguments. The first argument is an integer or +boolean value specifying the return value of a successful lock acquisition. The +remaining arugments are either of lockable type or integers indexing into +function parameters of lockable type. If only one argument is given, the +acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> + +<h4 id="ts_uf">unlock_function(...)</h4> + +<p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function +declaration to specify that the function release all listed locks. This +attribute takes zero or more arguments: either of lockable type or integers +indexing into function parameters of lockable type. If no arguments are given, +the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> + +<h4 id="ts_lr">lock_returned(l)</h4> + +<p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function +declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt> +must be of lockable type). This annotation is used to aid in resolving lock +expressions.</p> + +<h4 id="ts_le">locks_excluded(...)</h4> + +<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration +to specify that the function must not be called with the listed locks. Arguments +must be lockable type, and there must be at least one argument.</p> + +<h4 id="ts_elr">exclusive_locks_required(...)</h4> + +<p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function +declaration to specify that the function must be called while holding the listed +exclusive locks. Arguments must be lockable type, and there must be at +least one argument.</p> + +<h4 id="ts_slr">shared_locks_required(...)</h4> + +<p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function +declaration to specify that the function must be called while holding the listed +shared locks. Arguments must be lockable type, and there must be at +least one argument.</p> + </div> </body> </html> diff --git a/docs/UsersManual.html b/docs/UsersManual.html index 639892714ef8..9d7981919c28 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -39,6 +39,7 @@ td { <li><a href="#diagnostics_categories">Diagnostic Categories</a></li> <li><a href="#diagnostics_commandline">Controlling Diagnostics via Command Line Flags</a></li> <li><a href="#diagnostics_pragmas">Controlling Diagnostics via Pragmas</a></li> + <li><a href="#diagnostics_enable_everything">Enabling All Warnings</a></li> <li><a href="#analyzer_diagnositics">Controlling Static Analyzer Diagnostics</a></li> </ul> </li> @@ -626,6 +627,16 @@ GCC do not support the exact same set of warnings, so even when using GCC compatible #pragmas there is no guarantee that they will have identical behaviour on both compilers. </p> +<h4 id="diagnostics_enable_everything">Enabling All Warnings</h4> + +<p>In addition to the traditional <tt>-W</tt> flags, one can enable <b>all</b> + warnings by passing <tt>-Weverything</tt>. + This works as expected with <tt>-Werror</tt>, + and also includes the warnings from <tt>-pedantic</tt>.</p> + +<p>Note that when combined with <tt>-w</tt> (which disables all warnings), that + flag wins.</p> + <h4 id="analyzer_diagnositics">Controlling Static Analyzer Diagnostics</h4> <p>While not strictly part of the compiler, the diagnostics from Clang's <a @@ -1059,18 +1070,28 @@ Clang assumes directories as below;</p> <h5>MinGW-w64</h5> -<p>For x32(i686-w64-mingw32), it is not supported yet.</p> - -<p>For x64(x86_64-w64-mingw32), <a href="http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20110321/118499.html">an essential patch(LLVM's r128206)</a> would be needed. It is incompatible to <a href="http://tdm-gcc.tdragon.net/development">TDM-GCC</a> due to the definition of symbol "<code>___chkstk</code>". Clang assumes as below;<p> +<p>For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang assumes as below;<p> <ul> -<li><tt>C:/mingw/x86_64-w64-mingw32/include</tt></li> -<li><tt>C:/mingw/x86_64-w64-mingw32/include/c++/4.5.[23]</tt></li> -<li>GCC driver "gcc.exe" to build x86_64-w64-mingw32 binary.</li> +<li><tt>GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)</tt></li> +<li><tt>some_directory/bin/gcc.exe</tt></li> +<li><tt>some_directory/bin/clang.exe</tt></li> +<li><tt>some_directory/bin/clang++.exe</tt></li> +<li><tt>some_directory/bin/../include/c++/GCC_version</tt></li> +<li><tt>some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</tt></li> +<li><tt>some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</tt></li> +<li><tt>some_directory/bin/../include/c++/GCC_version/backward</tt></li> +<li><tt>some_directory/bin/../x86_64-w64-mingw32/include</tt></li> +<li><tt>some_directory/bin/../i686-w64-mingw32/include</tt></li> +<li><tt>some_directory/bin/../include</tt></li> </ul> -<p><a href="http://llvm.org/bugs/show_bug.cgi?id=8833">Some tests might fail</a> -on x64.</p> +<p>This directory layout is standard for any toolchain you will find on the official <a href="mingw-w64.sourceforge.net">MinGW-w64 website</a>. + +<p>Clang expects the GCC executable "gcc.exe" compiled for i686-w64-mingw32 (or x86_64-w64-mingw32) to be present on PATH.</p> + +<p><a href="http://llvm.org/bugs/show_bug.cgi?id=9072">Some tests might fail</a> +on x86_64-w64-mingw32.</p> </div> </body> diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index ed9ffcb85a53..7f3292c85d56 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 = NO +CREATE_SUBDIRS = YES # 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/doxygen.css b/docs/doxygen.css index f105e202761f..9780b98db2c7 100644 --- a/docs/doxygen.css +++ b/docs/doxygen.css @@ -370,9 +370,39 @@ H2 { H3 { font-size: 100%; } + +H2, H3 { + border-bottom: 2px solid; + margin-top: 2em; +} + A.qindex {} A.qindexRef {} A.el { text-decoration: none; font-weight: bold } A.elRef { font-weight: bold } A.code { text-decoration: none; font-weight: normal; color: #4444ee } A.codeRef { font-weight: normal; color: #4444ee } + +div.memitem { + border: 1px solid #999999; + margin-top: 1.0em; + margin-bottom: 1.0em; + -webkit-border-radius: 0.5em; + -webkit-box-shadow: 3px 3px 6px #777777; + -moz-border-radius: 0.5em; + -moz-box-shadow: black 3px 3px 3px; +} + +div.memproto { + background-color: #E3E4E5; + padding: 0.25em 0.5em; + -webkit-border-top-left-radius: 0.5em; + -webkit-border-top-right-radius: 0.5em; + -moz-border-radius-topleft: 0.5em; + -moz-border-radius-topright: 0.5em; +} + +div.memdoc { + padding-left: 1em; + padding-right: 1em; +} diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod index 704cc8743ba6..964b143ac9eb 100644 --- a/docs/tools/clang.pod +++ b/docs/tools/clang.pod @@ -459,7 +459,13 @@ Add the specified directory to the search path for framework include files. =item B<-nostdinc> -Do not search the standard system directories for include files. +Do not search the standard system directories or compiler builtin directories +for include files. + +=item B<-nostdlibinc> + +Do not search the standard system directories for include files, but do search +compiler builting include directories. =item B<-nobuiltininc> |