[libcxx] Slightly improved policy for handling experimental features

Summary: Following the discussion on the libcxx-dev mailing list (http://lists.llvm.org/pipermail/libcxx-dev/2019-May/000358.html), this implements the new policy for handling experimental features and their deprecation. We basically add a deprecation warning for std::experimental::filesystem, and we remove a bunch of <experimental/*> headers that were now empty. Reviewers: mclow.lists, EricWF Subscribers: mgorny, christof, jkorous, dexonsmith, arphaman, libcxx-commits, jfb Tags: #libc Differential Revision: https://reviews.llvm.org/D62428 llvm-svn: 363072
llvm · Jun 11, 2019 · 776acf2 · 776acf2
1 parent 10ed681
commit 776acf2
Show file tree

Hide file tree

Showing 36 changed files with 238 additions and 697 deletions.
diff --git a/libcxx/docs/DesignDocs/ExperimentalFeatures.rst b/libcxx/docs/DesignDocs/ExperimentalFeatures.rst
diff --git a/libcxx/docs/UsingLibcxx.rst b/libcxx/docs/UsingLibcxx.rst
@@ -84,6 +84,9 @@ page.
     * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
       library will not remain compatible between versions.
     * No guarantees of API or ABI stability are provided.
+    * When we implement the standardized version of an experimental feature,
+      the experimental feature is removed two releases after the non-experimental
+      version has shipped. The full policy is explained :ref:`here <experimental features>`.
 
 Using libc++ on Linux
 =====================

diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst
@@ -137,6 +137,7 @@ Design Documents
    DesignDocs/DebugMode
    DesignDocs/CapturingConfigInfo
    DesignDocs/ABIVersioning
+   DesignDocs/ExperimentalFeatures
    DesignDocs/VisibilityMacros
    DesignDocs/ThreadingSupportAPI
    DesignDocs/FileTimeType

diff --git a/libcxx/include/CMakeLists.txt b/libcxx/include/CMakeLists.txt
@@ -65,8 +65,6 @@ set(files
   experimental/__config
   experimental/__memory
   experimental/algorithm
-  experimental/any
-  experimental/chrono
   experimental/coroutine
   experimental/deque
   experimental/filesystem
@@ -76,17 +74,11 @@ set(files
   experimental/list
   experimental/map
   experimental/memory_resource
-  experimental/numeric
-  experimental/optional
   experimental/propagate_const
-  experimental/ratio
   experimental/regex
   experimental/set
   experimental/simd
   experimental/string
-  experimental/string_view
-  experimental/system_error
-  experimental/tuple
   experimental/type_traits
   experimental/unordered_map
   experimental/unordered_set

diff --git a/libcxx/include/experimental/__config b/libcxx/include/experimental/__config
@@ -36,8 +36,14 @@
   namespace chrono { namespace experimental { inline namespace fundamentals_v1 {
 #define _LIBCPP_END_NAMESPACE_CHRONO_LFTS _LIBCPP_END_NAMESPACE_STD } } }
 
+#if defined(_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM)
+#   define _LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM /* nothing */
+#else
+#   define _LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM __attribute__((deprecated("std::experimental::filesystem has now been deprecated in favor of C++17's std::filesystem. Please stop using it and start using std::filesystem. This experimental version will be removed in LLVM 11. You can remove this warning by defining the _LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM macro.")))
+#endif
+
 #define _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL_FILESYSTEM \
-    _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL namespace filesystem { \
+    _LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL namespace filesystem _LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM { \
     inline namespace v1 {
 
 #define _LIBCPP_END_NAMESPACE_EXPERIMENTAL_FILESYSTEM \

diff --git a/libcxx/include/experimental/any b/libcxx/include/experimental/any
diff --git a/libcxx/include/experimental/chrono b/libcxx/include/experimental/chrono
diff --git a/libcxx/include/experimental/numeric b/libcxx/include/experimental/numeric
diff --git a/libcxx/include/experimental/optional b/libcxx/include/experimental/optional
diff --git a/libcxx/include/experimental/ratio b/libcxx/include/experimental/ratio
diff --git a/libcxx/include/experimental/string_view b/libcxx/include/experimental/string_view
diff --git a/libcxx/include/experimental/system_error b/libcxx/include/experimental/system_error
diff --git a/libcxx/include/experimental/tuple b/libcxx/include/experimental/tuple
diff --git a/libcxx/test/libcxx/experimental/diagnostics/syserr/use_header_warning.fail.cpp b/libcxx/test/libcxx/experimental/diagnostics/syserr/use_header_warning.fail.cpp
diff --git a/libcxx/test/libcxx/experimental/diagnostics/syserr/version.pass.cpp b/libcxx/test/libcxx/experimental/diagnostics/syserr/version.pass.cpp
diff --git a/libcxx/test/libcxx/experimental/filesystem/deprecated.fail.cpp b/libcxx/test/libcxx/experimental/filesystem/deprecated.fail.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
+//
+//===----------------------------------------------------------------------===//
+
+// REQUIRES: verify-support
+// UNSUPPORTED: c++98, c++03
+
+// <experimental/filesystem>
+
+#include <experimental/filesystem>
+
+using namespace std::experimental::filesystem; // expected-error {{'filesystem' is deprecated: std::experimental::filesystem has now been deprecated in favor of C++17's std::filesystem. Please stop using it and start using std::filesystem. This experimental version will be removed in LLVM 11. You can remove this warning by defining the _LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM macro.}}
+
+int main(int, char**) {
+  return 0;
+}
diff --git a/libcxx/test/libcxx/experimental/filesystem/version.pass.cpp b/libcxx/test/libcxx/experimental/filesystem/version.pass.cpp
@@ -8,6 +8,8 @@
 
 // <experimental/filesystem>
 
+#define _LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_FILESYSTEM
+
 #include <experimental/filesystem>
 
 #include "test_macros.h"

diff --git a/libcxx/test/libcxx/experimental/numerics/numeric.ops/use_header_warning.fail.cpp b/libcxx/test/libcxx/experimental/numerics/numeric.ops/use_header_warning.fail.cpp
diff --git a/libcxx/test/libcxx/experimental/numerics/numeric.ops/version.pass.cpp b/libcxx/test/libcxx/experimental/numerics/numeric.ops/version.pass.cpp
diff --git a/libcxx/test/libcxx/experimental/strings/string.view/use_header_warning.fail.cpp b/libcxx/test/libcxx/experimental/strings/string.view/use_header_warning.fail.cpp
diff --git a/libcxx/test/libcxx/experimental/strings/string.view/version.pass.cpp b/libcxx/test/libcxx/experimental/strings/string.view/version.pass.cpp