r308044 - Add documentation for @available
Aaron Ballman via cfe-commits
cfe-commits at lists.llvm.org
Mon Jul 17 05:39:04 PDT 2017
On Sun, Jul 16, 2017 at 7:49 PM, Nico Weber <thakis at chromium.org> wrote:
> Aaron, https://clang.llvm.org/docs/AttributeReference.html#availability
> 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?
No, it's expected to update once a day, usually pretty early in the
morning EST (ridiculously early PST).
Tanya, I've not seen any failure emails for building from AttrDocs.td.
Did I get removed from that list when we updated? If so, I'm happy to
continue to receive it to help resolve problems, but in the interim,
do you happen to know more about what's going on?
Thanks!
~Aaron
>
> On Fri, Jul 14, 2017 at 2:40 PM, Nico Weber via cfe-commits
> <cfe-commits at lists.llvm.org> wrote:
>>
>> Author: nico
>> Date: Fri Jul 14 11:40:52 2017
>> New Revision: 308044
>>
>> URL: http://llvm.org/viewvc/llvm-project?rev=308044&view=rev
>> Log:
>> Add documentation for @available
>>
>> https://reviews.llvm.org/D35379
>>
>> Modified:
>> cfe/trunk/docs/LanguageExtensions.rst
>> cfe/trunk/include/clang/Basic/AttrDocs.td
>>
>> Modified: cfe/trunk/docs/LanguageExtensions.rst
>> URL:
>> http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=308044&r1=308043&r2=308044&view=diff
>>
>> ==============================================================================
>> --- cfe/trunk/docs/LanguageExtensions.rst (original)
>> +++ cfe/trunk/docs/LanguageExtensions.rst Fri Jul 14 11:40:52 2017
>> @@ -1271,6 +1271,87 @@ Further examples of these attributes are
>> Query for these features with ``__has_attribute(ns_consumed)``,
>> ``__has_attribute(ns_returns_retained)``, etc.
>>
>> +Objective-C @available
>> +----------------------
>> +
>> +It is possible to use the newest SDK but still build a program that can
>> run on
>> +older versions of macOS and iOS by passing ``-mmacosx-version-info=`` /
>> +``--miphoneos-version-min=``.
>> +
>> +Before LLVM 5.0, when calling a function that exists only in the OS
>> that's
>> +newer than the target OS (as determined by the minimum deployment
>> version),
>> +programmers had to carefully check if the function exists at runtime,
>> using
>> +null checks for weakly-linked C functions, ``+class`` for Objective-C
>> classes,
>> +and ``-respondsToSelector:`` or ``+instancesRespondToSelector:`` for
>> +Objective-C methods. If such a check was missed, the program would
>> compile
>> +fine, run fine on newer systems, but crash on older systems.
>> +
>> +As of LLVM 5.0, ``-Wunguarded-availability`` uses the `availability
>> attributes
>> +<http://clang.llvm.org/docs/AttributeReference.html#availability>`_
>> together
>> +with the new ``@available()`` keyword to assist with this issue.
>> +When a method that's introduced in the OS newer than the target OS is
>> called, a
>> +-Wunguarded-availability warning is emitted if that call is not guarded:
>> +
>> +.. code-block:: objc
>> +
>> + void my_fun(NSSomeClass* var) {
>> + // If fancyNewMethod was added in e.g. macOS 10.12, but the code is
>> + // built with -mmacosx-version-min=10.11, then this unconditional
>> call
>> + // will emit a -Wunguarded-availability warning:
>> + [var fancyNewMethod];
>> + }
>> +
>> +To fix the warning and to avoid the crash on macOS 10.11, wrap it in
>> +``if(@available())``:
>> +
>> +.. code-block:: objc
>> +
>> + void my_fun(NSSomeClass* var) {
>> + if (@available(macOS 10.12, *)) {
>> + [var fancyNewMethod];
>> + } else {
>> + // Put fallback behavior for old macOS versions (and for non-mac
>> + // platforms) here.
>> + }
>> + }
>> +
>> +The ``*`` is required and means that platforms not explicitly listed will
>> take
>> +the true branch, and the compiler will emit ``-Wunguarded-availability``
>> +warnings for unlisted platforms based on those platform's deployment
>> target.
>> +More than one platform can be listed in ``@available()``:
>> +
>> +.. code-block:: objc
>> +
>> + void my_fun(NSSomeClass* var) {
>> + if (@available(macOS 10.12, iOS 10, *)) {
>> + [var fancyNewMethod];
>> + }
>> + }
>> +
>> +If the caller of ``my_fun()`` already checks that ``my_fun()`` is only
>> called
>> +on 10.12, then add an `availability attribute
>> +<http://clang.llvm.org/docs/AttributeReference.html#availability>`_ to
>> it,
>> +which will also suppress the warning and require that calls to my_fun()
>> are
>> +checked:
>> +
>> +.. code-block:: objc
>> +
>> + API_AVAILABLE(macos(10.12)) void my_fun(NSSomeClass* var) {
>> + [var fancyNewMethod]; // Now ok.
>> + }
>> +
>> +``@available()`` is only available in Objective-C code. To use the
>> feature
>> +in C and C++ code, use the ``__builtin_available()`` spelling instead.
>> +
>> +If existing code uses null checks or ``-respondsToSelector:``, it should
>> +be changed to use ``@available()`` (or ``__builtin_available``) instead.
>> +
>> +``-Wunguarded-availability`` is disabled by default, but
>> +``-Wunguarded-availability-new``, which only emits this warning for APIs
>> +that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and
>> +tvOS >= 11, is enabled by default.
>> +
>> +.. _langext-overloading:
>>
>> Objective-C++ ABI: protocol-qualifier mangling of parameters
>> ------------------------------------------------------------
>> @@ -1287,8 +1368,6 @@ parameters of protocol-qualified type.
>> Query the presence of this new mangling with
>> ``__has_feature(objc_protocol_qualifier_mangling)``.
>>
>> -.. _langext-overloading:
>> -
>> Initializer lists for complex numbers in C
>> ==========================================
>>
>>
>> Modified: cfe/trunk/include/clang/Basic/AttrDocs.td
>> URL:
>> http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttrDocs.td?rev=308044&r1=308043&r2=308044&view=diff
>>
>> ==============================================================================
>> --- cfe/trunk/include/clang/Basic/AttrDocs.td (original)
>> +++ cfe/trunk/include/clang/Basic/AttrDocs.td Fri Jul 14 11:40:52 2017
>> @@ -910,13 +910,13 @@ the function declaration for a hypotheti
>>
>> void f(void)
>> __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
>>
>> -The availability attribute states that ``f`` 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
>> +The availability attribute states that ``f`` was introduced in macOS
>> 10.4,
>> +deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
>> is used by Clang to determine when it is safe to use ``f``: for example,
>> if
>> -Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
>> -succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the
>> call
>> +Clang is instructed to compile code for macOS 10.5, a call to ``f()``
>> +succeeds. If Clang is instructed to compile code for macOS 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
>> +Finally, if Clang is instructed to compile code for macOS 10.7, the call
>> fails because ``f()`` is no longer available.
>>
>> The availability attribute is a comma-separated list starting with the
>> @@ -961,7 +961,7 @@ are:
>> command-line arguments.
>>
>> ``macos``
>> - Apple's Mac OS X operating system. The minimum deployment target is
>> + Apple's macOS operating system. The minimum deployment target is
>> specified by the ``-mmacosx-version-min=*version*`` command-line
>> argument.
>> ``macosx`` is supported for backward-compatibility reasons, but it is
>> deprecated.
>> @@ -1015,6 +1015,19 @@ When one method overrides another, the o
>> - (id)method __attribute__((availability(macos,introduced=10.3))); //
>> okay: method moved into base class later
>> - (id)method __attribute__((availability(macos,introduced=10.5))); //
>> error: this method was available via the base class in 10.4
>> @end
>> +
>> +Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
>> +``<os/availability.h>`` can simplify the spelling:
>> +
>> +.. code-block:: objc
>> +
>> + @interface A
>> + - (id)method API_AVAILABLE(macos(10.11)));
>> + - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
>> + @end
>> +
>> +Also see the documentation for `@available
>>
>> +<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-@available>`_
>> }];
>> }
>>
>>
>>
>> _______________________________________________
>> cfe-commits mailing list
>> cfe-commits at lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
>
>
More information about the cfe-commits
mailing list