r308044 - Add documentation for @available
via cfe-commits
cfe-commits at lists.llvm.org
Tue Jul 18 08:30:44 PDT 2017
Its getting an error. Will update in a bit when I can.
-Tanya
> On Jul 18, 2017, at 8:07 AM, Nico Weber <thakis at chromium.org> wrote:
>
>> On Mon, Jul 17, 2017 at 8:39 AM, Aaron Ballman <aaron at aaronballman.com> wrote:
>> 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?
>
> Tanya, ping?
>
>>
>> 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
>> >
>> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20170718/05645c43/attachment-0001.html>
More information about the cfe-commits
mailing list