r308044 - Add documentation for @available

Tanya Lattner via cfe-commits cfe-commits at lists.llvm.org
Tue Jul 18 22:22:53 PDT 2017 

> 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 <mailto:aaron at aaronballman.com>> wrote:
> On Sun, Jul 16, 2017 at 7:49 PM, Nico Weber <thakis at chromium.org <mailto:thakis at chromium.org>> wrote:
> > Aaron, https://clang.llvm.org/docs/AttributeReference.html#availability <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?
>  

FYI this is fixed. Had a permission problem that occurred after the SVN move.

Aaron, I will add you back to the script email as its just sending to the mailing list right now.

-Tanya


> 
> Thanks!
> 
> ~Aaron
> 
> >
> > On Fri, Jul 14, 2017 at 2:40 PM, Nico Weber via cfe-commits
> > <cfe-commits at lists.llvm.org <mailto: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 <http://llvm.org/viewvc/llvm-project?rev=308044&view=rev>
> >> Log:
> >> Add documentation for @available
> >>
> >> https://reviews.llvm.org/D35379 <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 <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 <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 <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 <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 <http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-@available>>`_
> >>    }];
> >>  }
> >>
> >>
> >>
> >> _______________________________________________
> >> cfe-commits mailing list
> >> cfe-commits at lists.llvm.org <mailto:cfe-commits at lists.llvm.org>
> >> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits <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/2e721138/attachment-0001.html>

More information about the cfe-commits mailing list