[libc++] Take advantage of -fexperimental-library in libc++

[ldionne]

Summary

When -fexperimental-library is passed, libc++ will now pick up the
appropriate __has_feature flag defined by Clang to enable the
experimental library features.

As a fly-by, also update the documentation for the various TSes.

[Mordante]

Nice to see the TS page updated! All changes LGTM.

[philnik]

LGTM % nit.

libcxx/docs/DesignDocs/ExperimentalFeatures.rst

175

[ldionne]

Address comment, fix test.

libcxx/docs/DesignDocs/ExperimentalFeatures.rst

 +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
 | 14      | Reflection Library                                    |                    |                                          | Not part of C++17       |
 +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+
 
 
 `FileSystem TS <https://wg21.link/N4100>`__
 -------------------------------------------
 The FileSystem TS was accepted (in totality) for C++17.
-The FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and will be removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0).
+The FileSystem TS implementation was shipped in namespace ``std`` in LLVM 7.0, and was
+removed in LLVM 11.0 (due to the lack of deprecation warnings before LLVM 9.0).
 
 Parallelism TS `V1 <https://wg21.link/N4507>`__ and `V2 <https://wg21.link/N4706>`__
 ------------------------------------------------------------------------------------
 Some (most) of the Parallelism TS was accepted for C++17.
 We have not yet shipped an implementation of the Parallelism TS.
 
 `Coroutines TS <https://wg21.link/N4680>`__
 -------------------------------------------
-The Coroutines TS is not yet part of a shipping standard.
-We are shipping (as of v5.0) an implementation of the Coroutines TS in namespace ``std::experimental``.
+The Coroutines TS was accepted for C++20.
+An implementation of the Coroutines TS was shipped in LLVM 5.0 in namespace ``std::experimental``,
+and C++20 Coroutines shipped in LLVM 14.0. The implementation of the Coroutines TS in ``std::experimental``
+will be removed in LLVM 16.0.
 
 `Networking TS <https://wg21.link/N4656>`__
 -------------------------------------------
 The Networking TS is not yet part of a shipping standard.
 We have not yet shipped an implementation of the Networking TS.
 
 `Ranges TS <https://wg21.link/N4685>`__
 ---------------------------------------
-The Ranges TS is not yet part of a shipping standard.
-We have not yet shipped an implementation of the Ranges TS.
+The Ranges TS was accepted for C++20.
+We will not ship an implementation of the Ranges TS, however we are actively working on
+the implementation of C++20 Ranges.
 
 `Concepts TS <https://wg21.link/N4641>`__
 -----------------------------------------
-The Concepts TS is not yet part of a shipping standard, but it has been adopted into the C++20 working draft.
-We have not yet shipped an implementation of the Concepts TS.
+The Concepts TS was accepted for C++20.
+We will not ship an implementation of the Concepts TS, however we are shipping an
+implementation of C++20 Concepts.
 
 `Concurrency TS <https://wg21.link/P0159>`__
 --------------------------------------------
 The Concurrency TS was adopted in Kona (2015).
 None of the Concurrency TS was accepted for C++17.
 We have not yet shipped an implementation of the Concurrency TS.
 
 .. +---------+-------------------------------------------------------+--------------------+------------------------------------------+-------------------------+

libcxx/docs/ReleaseNotes.rst

- ``std::pop_heap`` now uses an algorithm known as "bottom-up heapsort" or
   elements using move-assignment instead of ``std::swap``.
 
 - Libc++ now supports a variety of assertions that can be turned on to help catch
   undefined behavior in user code. This new support is now separate from the old
   (and incomplete) Debug Mode. Vendors can select whether the library they ship
   should include assertions or not by default. For details, see
   :ref:`the documentation <assertions-mode>` about this new feature.
 
+- Clang now implements the ``-fexperimental-library`` flag. This flag can be used to
+  enable experimental library features such as TSes and other in-progress work like
+  ``<ranges>`` and ``<format>``. Using this flag makes it unnecessary to manually link
+  against ``libc++experimental.a`` -- just use ``-fexperimental-library`` and the
+  compiler will do what's needed to make experimental features work. However, be
+  aware that experimental features are not stable!
+
 - The implementation of the function ``std::to_chars`` for integral types using
   base 10 has moved from the dylib to the header. This means the function no
   longer has a minimum deployment target.
 
 - The performance for ``std::to_chars``, for integral types using base 2, 8,
   10, or 16 has been improved.
 
 - The functions ``std::from_chars`` and ``std::to_chars`` now have 128-bit integral

libcxx/docs/Status/Cxx20.rst

.. csv-table::
    :file: Cxx20Papers.csv
    :header-rows: 1
    :widths: auto
 
 .. note::
 
    .. [#note-P0600] P0600: The missing bits in P0600 are in |sect|\ [mem.res.class] and |sect|\ [mem.poly.allocator.class].
    .. [#note-P0645] P0645: The paper is implemented but still marked as an incomplete feature
-      (the feature-test macro is not set and the libary is only available when built with ``-D_LIBCPP_ENABLE_EXPERIMENTAL``).
+      (the feature-test macro is not set and the libary is only available when built with ``-fexperimental-library``).
       Not yet implemented LWG-issues will cause API and ABI breakage.
    .. [#note-P0966] P0966: It was previously erroneously marked as complete in version 8.0. See `bug 45368 <https://llvm.org/PR45368>`__.
    .. [#note-P0619] P0619: Only sections D.8, D.9, D.10 and D.13 are implemented. Sections D.4, D.7, D.11, D.12, and D.14 remain undone.
    .. [#note-P0883.1] P0883: shared_ptr and floating-point changes weren't applied as they themselves aren't implemented yet.
    .. [#note-P0883.2] P0883: ``ATOMIC_FLAG_INIT`` was marked deprecated in version 14.0, but was undeprecated with the implementation of LWG3659 in version 15.0.
    .. [#note-P2231] P2231: Optional is complete. The changes to variant haven't been implemented yet.
 
 

libcxx/docs/UsingLibcxx.rst

 
 Enabling experimental C++ Library features
 ==========================================
 
 Libc++ provides implementations of some experimental features. Experimental features
 are either Technical Specifications (TSes) or official features that were voted to
 the Standard but whose implementation is not complete or stable yet in libc++. Those
 are disabled by default because they are neither API nor ABI stable. However, the
-``_LIBCPP_ENABLE_EXPERIMENTAL`` macro can be defined to turn those features on. Note
-that you will also need to link to the appropriate ``libc++experimental.a`` static
-archive.
+``-fexperimental-library`` compiler flag can be defined to turn those features on.
 
 .. warning::
-  Experimental libraries are Experimental.
+  Experimental libraries are experimental.
     * The contents of the ``<experimental/...>`` headers and the associated static
       library will not remain compatible between versions.
     * No guarantees of API or ABI stability are provided.
     * When the standardized version of an experimental feature is implemented,
       the experimental feature is removed two releases after the non-experimental
       version has shipped. The full policy is explained :ref:`here <experimental features>`.
 
+.. note::
+  On compilers that do not support the ``-fexperimental-library`` flag, users can
+  define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against the
+  appropriate static library (usually shipped as ``libc++experimental.a``) to get
+  access to experimental library features.
+
 
 Using libc++ when it is not the system default
 ==============================================
 
 On systems where libc++ is provided but is not the default, Clang provides a flag
 called ``-stdlib=`` that can be used to decide which standard library is used.
 Using ``-stdlib=libc++`` will select libc++:
 

libcxx/include/__config

 #      define _LIBCPP_ABI_ITANIUM
 #    endif
 #  endif
 
 #  if defined(_LIBCPP_ABI_MICROSOFT) && !defined(_LIBCPP_NO_VCRUNTIME)
 #    define _LIBCPP_ABI_VCRUNTIME
 #  endif
 
+#  if __has_feature(experimental_library)
+#    ifndef _LIBCPP_ENABLE_EXPERIMENTAL
+#      define _LIBCPP_ENABLE_EXPERIMENTAL
+#    endif
+#  endif
+
 // Incomplete features get their own specific disabling flags. This makes it
 // easier to grep for target specific flags once the feature is complete.
 #  if !defined(_LIBCPP_ENABLE_EXPERIMENTAL) && !defined(_LIBCPP_BUILDING_LIBRARY)
 #    define _LIBCPP_HAS_NO_INCOMPLETE_FORMAT
 #    define _LIBCPP_HAS_NO_INCOMPLETE_RANGES
 #  endif
 
 // Need to detect which libc we're using if we're on Linux.

libcxx/test/libcxx/experimental/fexperimental-library.compile.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// This test ensures that passing `-fexperimental-library` results in experimental
+// library features being enabled.
+
+// GCC does not support the -fexperimental-library flag
+// UNSUPPORTED: gcc
+
+// Clang does not support the -fexperimental-library flag before LLVM 15.0
+// UNSUPPORTED: clang-13, clang-14
+
+// AppleClang does not support the -fexperimental-library flag yet
+// UNSUPPORTED: apple-clang-13
+
+// Clang on AIX currently pretends that it is Clang 15, even though it is not (as of writing
+// this, LLVM 15 hasn't even been branched yet).
+// UNSUPPORTED: clang-15 && buildhost=aix
+
+// ADDITIONAL_COMPILE_FLAGS: -fexperimental-library
+
+#include <version>
+
+#ifdef _LIBCPP_HAS_NO_INCOMPLETE_FORMAT
+#   error "-fexperimental-library should enable <format>"
+#endif
+
+#ifdef _LIBCPP_HAS_NO_INCOMPLETE_RANGES
+#   error "-fexperimental-library should enable <ranges>"
+#endif

libcxx/utils/libcxx/test/params.py

DEFAULT_PARAMETERS = [
   Parameter(name='enable_experimental', choices=[True, False], type=bool, default=True,
             help="Whether to enable tests for experimental C++ Library features.",
             actions=lambda experimental: [
               # When linking in MSVC mode via the Clang driver, a -l<foo>
               # maps to <foo>.lib, so we need to use -llibc++experimental here
               # to make it link against the static libc++experimental.lib.
               # We can't check for the feature 'msvc' in available_features
               # as those features are added after processing parameters.
-              #
-              # TODO: Switch to using the appropriate experimental compiler flag once
-              #       all compilers we support implement that flag.
               AddFeature('c++experimental'),
               PrependLinkFlag(lambda cfg: '-llibc++experimental' if _isMSVC(cfg) else '-lc++experimental'),
               AddCompileFlag('-D_LIBCPP_ENABLE_EXPERIMENTAL'),
             ] if experimental else [
               AddFeature('libcpp-has-no-incomplete-format'),
               AddFeature('libcpp-has-no-incomplete-ranges')
             ]),