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?
On Fri, Jul 14, 2017 at 2:40 PM, Nico Weber via cfe-commits < cfe-commits@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@lists.llvm.org > http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits >
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
