r308044 - Add documentation for @available
Nico Weber via cfe-commits
cfe-commits at lists.llvm.org
Sun Jul 16 16:49:55 PDT 2017
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 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- at 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/20170716/d09874b6/attachment-0001.html>
More information about the cfe-commits
mailing list