libcxx/docs/DesignDocs/AvailabilityMarkup.rst

===================
Availability Markup
===================

.. contents::
   :local:

Overview
========

Libc++ is used as a system library on macOS and iOS (amongst others). In order
for users to be able to compile a binary that is intended to be deployed to an
older version of the platform, clang provides the
`availability attribute <https://clang.llvm.org/docs/AttributeReference.html#availability>`_
that can be placed on declarations to describe the lifecycle of a symbol in the
library.

Design
======

When a new feature is introduced that requires dylib support, a macro should be
created in include/__config to mark this feature as unavailable for all the
systems. For example::

    // Define availability macros.
    #if defined(_LIBCPP_USE_AVAILABILITY_APPLE)
    #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
    #else  if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR)
    #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
	#else
    #define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
    #endif

When the library is updated by the platform vendor, the markup can be updated.
For example::

    #define _LIBCPP_AVAILABILITY_SHARED_MUTEX                                  \
      __attribute__((availability(macosx,strict,introduced=10.12)))            \
      __attribute__((availability(ios,strict,introduced=10.0)))                \
      __attribute__((availability(tvos,strict,introduced=10.0)))               \
      __attribute__((availability(watchos,strict,introduced=3.0)))

In the source code, the macro can be added on a class if the full class requires
type info from the library for example::

	_LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL
	class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access
	    : public std::logic_error {

or on a particular symbol:

    _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_AVAILABILITY_SIZED_NEW_DELETE void  operator delete(void* __p, std::size_t __sz) _NOEXCEPT;


Testing
=======

Some parameters can be passed to lit to run the test-suite and exercising the
availability.

* The `platform` parameter controls the deployement target. For example lit can
  be invoked with `--param=platform=macosx10.8`. Default is the current host.
* The `use_system_cxx_lib` parameter indicates to use another library than the
  just built one. Invoking lit with `--param=use_system_cxx_lib=true` will run
  the test-suite against the host system library. Alternatively a path to the
  directory containing a specific prebuilt libc++ can be used, for example:
  `--param=use_system_cxx_lib=/path/to/macOS/10.8/`.
* The `with_availability` boolean parameter enables the availability markup.

Tests can be marked as XFAIL based on multiple features made available by lit:


* if either `use_system_cxx_lib` or  `with_availability` is passed to lit,
  assuming `--param=platform=macosx10.8` is passed as well the following
  features will be available:

  - availability
  - availability=x86_64
  - availability=macosx
  - availability=x86_64-macosx
  - availability=x86_64-apple-macosx10.8
  - availability=macosx10.8

  This feature is used to XFAIL a test that *is* using a class of a method marked
  as unavailable *and* that is expected to *fail* if deployed on an older system.

* if `use_system_cxx_lib` is passed to lit, the following features will also
  be available:

  - with_system_cxx_lib
  - with_system_cxx_lib=x86_64
  - with_system_cxx_lib=macosx
  - with_system_cxx_lib=x86_64-macosx
  - with_system_cxx_lib=x86_64-apple-macosx10.8
  - with_system_cxx_lib=macosx10.8

  This feature is used to XFAIL a test that is *not* using a class of a method
  marked as unavailable *but* that is expected to fail if deployed on an older
  system. For example if we know that it exhibits a but in the libc on a
  particular system version.

* if `with_availability` is passed to lit, the following features will also
  be available:

  - availability_markup
  - availability_markup=x86_64
  - availability_markup=macosx
  - availability_markup=x86_64-macosx
  - availability_markup=x86_64-apple-macosx10.8
  - availability_markup=macosx10.8

  This feature is used to XFAIL a test that *is* using a class of a method
  marked as unavailable *but* that is expected to *pass* if deployed on an older
  system. For example if it is using a symbol in a statically evaluated context.