<div dir="ltr">Aaron, <a href="https://clang.llvm.org/docs/AttributeReference.html#availability">https://clang.llvm.org/docs/AttributeReference.html#availability</a> still doesn't have the AttrDocs.td change I made in this change 2 days ago. Do I have to do anything to get it to update?</div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Jul 14, 2017 at 2:40 PM, Nico Weber via cfe-commits <span dir="ltr"><<a href="mailto:cfe-commits@lists.llvm.org" target="_blank">cfe-commits@lists.llvm.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: nico<br>
Date: Fri Jul 14 11:40:52 2017<br>
New Revision: 308044<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=308044&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project?rev=308044&view=rev</a><br>
Log:<br>
Add documentation for @available<br>
<br>
<a href="https://reviews.llvm.org/D35379" rel="noreferrer" target="_blank">https://reviews.llvm.org/<wbr>D35379</a><br>
<br>
Modified:<br>
cfe/trunk/docs/<wbr>LanguageExtensions.rst<br>
cfe/trunk/include/clang/Basic/<wbr>AttrDocs.td<br>
<br>
Modified: cfe/trunk/docs/<wbr>LanguageExtensions.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=308044&r1=308043&r2=308044&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project/cfe/trunk/docs/<wbr>LanguageExtensions.rst?rev=<wbr>308044&r1=308043&r2=308044&<wbr>view=diff</a><br>
==============================<wbr>==============================<wbr>==================<br>
--- cfe/trunk/docs/<wbr>LanguageExtensions.rst (original)<br>
+++ cfe/trunk/docs/<wbr>LanguageExtensions.rst Fri Jul 14 11:40:52 2017<br>
@@ -1271,6 +1271,87 @@ Further examples of these attributes are<br>
Query for these features with ``__has_attribute(ns_consumed)<wbr>``,<br>
``__has_attribute(ns_returns_<wbr>retained)``, etc.<br>
<br>
+Objective-C @available<br>
+----------------------<br>
+<br>
+It is possible to use the newest SDK but still build a program that can run on<br>
+older versions of macOS and iOS by passing ``-mmacosx-version-info=`` /<br>
+``--miphoneos-version-min=``.<br>
+<br>
+Before LLVM 5.0, when calling a function that exists only in the OS that's<br>
+newer than the target OS (as determined by the minimum deployment version),<br>
+programmers had to carefully check if the function exists at runtime, using<br>
+null checks for weakly-linked C functions, ``+class`` for Objective-C classes,<br>
+and ``-respondsToSelector:`` or ``+instancesRespondToSelector:<wbr>`` for<br>
+Objective-C methods. If such a check was missed, the program would compile<br>
+fine, run fine on newer systems, but crash on older systems.<br>
+<br>
+As of LLVM 5.0, ``-Wunguarded-availability`` uses the `availability attributes<br>
+<<a href="http://clang.llvm.org/docs/AttributeReference.html#availability" rel="noreferrer" target="_blank">http://clang.llvm.org/docs/<wbr>AttributeReference.html#<wbr>availability</a>>`_ together<br>
+with the new ``@available()`` keyword to assist with this issue.<br>
+When a method that's introduced in the OS newer than the target OS is called, a<br>
+-Wunguarded-availability warning is emitted if that call is not guarded:<br>
+<br>
+.. code-block:: objc<br>
+<br>
+ void my_fun(NSSomeClass* var) {<br>
+ // If fancyNewMethod was added in e.g. macOS 10.12, but the code is<br>
+ // built with -mmacosx-version-min=10.11, then this unconditional call<br>
+ // will emit a -Wunguarded-availability warning:<br>
+ [var fancyNewMethod];<br>
+ }<br>
+<br>
+To fix the warning and to avoid the crash on macOS 10.11, wrap it in<br>
+``if(@available())``:<br>
+<br>
+.. code-block:: objc<br>
+<br>
+ void my_fun(NSSomeClass* var) {<br>
+ if (@available(macOS 10.12, *)) {<br>
+ [var fancyNewMethod];<br>
+ } else {<br>
+ // Put fallback behavior for old macOS versions (and for non-mac<br>
+ // platforms) here.<br>
+ }<br>
+ }<br>
+<br>
+The ``*`` is required and means that platforms not explicitly listed will take<br>
+the true branch, and the compiler will emit ``-Wunguarded-availability``<br>
+warnings for unlisted platforms based on those platform's deployment target.<br>
+More than one platform can be listed in ``@available()``:<br>
+<br>
+.. code-block:: objc<br>
+<br>
+ void my_fun(NSSomeClass* var) {<br>
+ if (@available(macOS 10.12, iOS 10, *)) {<br>
+ [var fancyNewMethod];<br>
+ }<br>
+ }<br>
+<br>
+If the caller of ``my_fun()`` already checks that ``my_fun()`` is only called<br>
+on 10.12, then add an `availability attribute<br>
+<<a href="http://clang.llvm.org/docs/AttributeReference.html#availability" rel="noreferrer" target="_blank">http://clang.llvm.org/docs/<wbr>AttributeReference.html#<wbr>availability</a>>`_ to it,<br>
+which will also suppress the warning and require that calls to my_fun() are<br>
+checked:<br>
+<br>
+.. code-block:: objc<br>
+<br>
+ API_AVAILABLE(macos(10.12)) void my_fun(NSSomeClass* var) {<br>
+ [var fancyNewMethod]; // Now ok.<br>
+ }<br>
+<br>
+``@available()`` is only available in Objective-C code. To use the feature<br>
+in C and C++ code, use the ``__builtin_available()`` spelling instead.<br>
+<br>
+If existing code uses null checks or ``-respondsToSelector:``, it should<br>
+be changed to use ``@available()`` (or ``__builtin_available``) instead.<br>
+<br>
+``-Wunguarded-availability`` is disabled by default, but<br>
+``-Wunguarded-availability-<wbr>new``, which only emits this warning for APIs<br>
+that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and<br>
+tvOS >= 11, is enabled by default.<br>
+<br>
+.. _langext-overloading:<br>
<br>
Objective-C++ ABI: protocol-qualifier mangling of parameters<br>
------------------------------<wbr>------------------------------<br>
@@ -1287,8 +1368,6 @@ parameters of protocol-qualified type.<br>
Query the presence of this new mangling with<br>
``__has_feature(objc_protocol_<wbr>qualifier_mangling)``.<br>
<br>
-.. _langext-overloading:<br>
-<br>
Initializer lists for complex numbers in C<br>
==============================<wbr>============<br>
<br>
<br>
Modified: cfe/trunk/include/clang/Basic/<wbr>AttrDocs.td<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttrDocs.td?rev=308044&r1=308043&r2=308044&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-<wbr>project/cfe/trunk/include/<wbr>clang/Basic/AttrDocs.td?rev=<wbr>308044&r1=308043&r2=308044&<wbr>view=diff</a><br>
==============================<wbr>==============================<wbr>==================<br>
--- cfe/trunk/include/clang/Basic/<wbr>AttrDocs.td (original)<br>
+++ cfe/trunk/include/clang/Basic/<wbr>AttrDocs.td Fri Jul 14 11:40:52 2017<br>
@@ -910,13 +910,13 @@ the function declaration for a hypotheti<br>
<br>
void f(void) __attribute__((availability(<wbr>macos,introduced=10.4,<wbr>deprecated=10.6,obsoleted=10.<wbr>7)));<br>
<br>
-The availability attribute states that ``f`` was introduced in Mac OS X 10.4,<br>
-deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information<br>
+The availability attribute states that ``f`` was introduced in macOS 10.4,<br>
+deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information<br>
is used by Clang to determine when it is safe to use ``f``: for example, if<br>
-Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``<br>
-succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call<br>
+Clang is instructed to compile code for macOS 10.5, a call to ``f()``<br>
+succeeds. If Clang is instructed to compile code for macOS 10.6, the call<br>
succeeds but Clang emits a warning specifying that the function is deprecated.<br>
-Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call<br>
+Finally, if Clang is instructed to compile code for macOS 10.7, the call<br>
fails because ``f()`` is no longer available.<br>
<br>
The availability attribute is a comma-separated list starting with the<br>
@@ -961,7 +961,7 @@ are:<br>
command-line arguments.<br>
<br>
``macos``<br>
- Apple's Mac OS X operating system. The minimum deployment target is<br>
+ Apple's macOS operating system. The minimum deployment target is<br>
specified by the ``-mmacosx-version-min=*<wbr>version*`` command-line argument.<br>
``macosx`` is supported for backward-compatibility reasons, but it is<br>
deprecated.<br>
@@ -1015,6 +1015,19 @@ When one method overrides another, the o<br>
- (id)method __attribute__((availability(<wbr>macos,introduced=10.3))); // okay: method moved into base class later<br>
- (id)method __attribute__((availability(<wbr>macos,introduced=10.5))); // error: this method was available via the base class in 10.4<br>
@end<br>
+<br>
+Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from<br>
+``<os/availability.h>`` can simplify the spelling:<br>
+<br>
+.. code-block:: objc<br>
+<br>
+ @interface A<br>
+ - (id)method API_AVAILABLE(macos(10.11)));<br>
+ - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));<br>
+ @end<br>
+<br>
+Also see the documentation for `@available<br>
+<<a href="http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-@available" rel="noreferrer" target="_blank">http://clang.llvm.org/docs/<wbr>LanguageExtensions.html#<wbr>objective-c-@available</a>>`_<br>
}];<br>
}<br>
<br>
<br>
<br>
______________________________<wbr>_________________<br>
cfe-commits mailing list<br>
<a href="mailto:cfe-commits@lists.llvm.org">cfe-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/<wbr>mailman/listinfo/cfe-commits</a><br>
</blockquote></div><br></div>