thakis updated this revision to Diff 106652. thakis marked 3 inline comments as done. thakis added a comment.
sdy comments https://reviews.llvm.org/D35379 Files: docs/LanguageExtensions.rst include/clang/Basic/AttrDocs.td
Index: include/clang/Basic/AttrDocs.td =================================================================== --- include/clang/Basic/AttrDocs.td +++ include/clang/Basic/AttrDocs.td @@ -910,13 +910,13 @@ 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 @@ 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. @@ -1016,6 +1016,19 @@ - (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>`_ } def ExternalSourceSymbolDocs : Documentation { Index: docs/LanguageExtensions.rst =================================================================== --- docs/LanguageExtensions.rst +++ docs/LanguageExtensions.rst @@ -1271,7 +1271,88 @@ 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 @@ Query the presence of this new mangling with ``__has_feature(objc_protocol_qualifier_mangling)``. -.. _langext-overloading: - Initializer lists for complex numbers in C ==========================================
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
