[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 have not and 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

- The format functions (``std::format``, ``std::format_to``, ``std::format_to_n``, and
   When the format string is invalid this will make the code ill-formed instead
   of throwing an exception at run-time.  (This does not affect the ``v``
   functions.)
 
 - All format functions in ``<format>`` allow the usage of non-copyable types as
   argument for the formatting functions. This change causes bit fields to become
   invalid arguments for the formatting functions.
 
+- 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!
+
 API Changes
 -----------
 
 - The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting
   ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because
   they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we
   still feel that it is worth mentioning in the release notes in case some users
   had been doing it.

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
+
+// ADDITIONAL_COMPILE_FLAGS: -fexperimental-library
+
+#include <version>
+
+#ifndef _LIBCPP_HAS_NO_INCOMPLETE_FORMAT
+#   error "-fexperimental-library should enable <format>"
+#endif
+
+#ifndef _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')
             ]),