[libc++] Deprecate the _LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS macro (llvm#77692)

As described in llvm#69994, using the escape hatch makes us non-conforming
in C++20 due to incorrect constexpr-ness. It also leads to bad
diagnostics as reported by llvm#63900. We discussed the issue in the libc++
monthly meeting and we agreed that we should deprecate the macro in LLVM
18, and then remove it in LLVM 19 since it causes too many problems.

This patch does the first part of this -- it deprecates the macro.

Fixes llvm#69994
Fixes llvm#63900
Partially addresses llvm#75975

Author: ldionne

libcxx/docs/ReleaseNotes/18.rst

@@ -117,6 +117,12 @@ Deprecations and Removals
   and ``<experimental/vector>`` have been removed in LLVM 18, as all their contents will have been
   implemented in namespace ``std`` for at least two releases.
 
+- The macro ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` has been deprecated and will be removed
+  in LLVM 19. This macro used to re-enable redundant members of ``std::allocator<T>`` like ``pointer``,
+  ``reference``, ``rebind``, ``address``, ``max_size``, ``construct``, ``destroy``, and the two-argument
+  overload of ``allocate``. However, this led to the library being non-conforming due to incorrect
+  constexpr-ness.
+
 Upcoming Deprecations and Removals
 ----------------------------------
 
@@ -140,6 +146,9 @@ LLVM 19
 - The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` macro that changed the behavior for narrowing conversions
   in ``std::variant`` will be removed in LLVM 19.
 
+- The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` macro has been deprecated in LLVM 18 and will be removed
+  entirely in LLVM 19.
+
 LLVM 20
 ~~~~~~~
 

libcxx/include/__memory/allocator.h

@@ -31,6 +31,12 @@ _LIBCPP_BEGIN_NAMESPACE_STD
 template <class _Tp>
 class allocator;
 
+#if defined(_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS) && !defined(_LIBCPP_DISABLE_DEPRECATION_WARNINGS)
+#  pragma clang deprecated(                                                                                            \
+      _LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS,                                                                  \
+      "_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS is deprecated in LLVM 18 and will be removed in LLVM 19")
+#endif
+
 #if _LIBCPP_STD_VER <= 17 || defined(_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION)
 // These specializations shouldn't be marked _LIBCPP_DEPRECATED_IN_CXX17.
 // Specializing allocator<void> is deprecated, but not using it.

libcxx/test/libcxx/depr/depr.default.allocator/allocator.members/address.depr_in_cxx17.verify.cpp

@@ -16,7 +16,7 @@
 
 // UNSUPPORTED: c++03, c++11, c++14
 
-// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS
+// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS -Wno-deprecated-pragma
 
 #include <memory>
 

libcxx/test/libcxx/depr/depr.default.allocator/allocator.members/allocate.depr_in_cxx17.verify.cpp

@@ -15,7 +15,7 @@
 
 // UNSUPPORTED: c++03, c++11, c++14
 
-// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS
+// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS -Wno-deprecated-pragma
 
 #include <memory>
 

libcxx/test/libcxx/depr/depr.default.allocator/enable_removed_allocator_members.deprecated.verify.cpp

@@ -0,0 +1,20 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+// <memory>
+
+// Ensure that defining _LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS yields a
+// deprecation warning. We intend to issue a deprecation warning in LLVM 18
+// and remove the macro entirely in LLVM 19. As such, this test will be quite
+// short lived.
+
+// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS
+
+// UNSUPPORTED: clang-modules-build
+
+#include <memory> // expected-warning@* 1+ {{macro '_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS' has been marked as deprecated}}