[libcxx-commits] [PATCH] D107596: [libc++][doc] Improve contributor documentation.

[Mark de Wever via Phabricator via libcxx-commits]

Mordante created this revision.
Mordante added a reviewer: ldionne.
Mordante requested review of this revision.
Herald added a project: libc++.
Herald added a subscriber: libcxx-commits.
Herald added a reviewer: libc++.

Shorty before branching  LLVM 13 a new CMake option was added. This
option `LIBCXX_ENABLE_INCOMPLETE_FEATURES` lacks the contributor
documentation. This patch rectifies that issue.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D107596

Files:
  libcxx/docs/Contributing.rst


Index: libcxx/docs/Contributing.rst
===================================================================
--- libcxx/docs/Contributing.rst
+++ libcxx/docs/Contributing.rst
@@ -66,3 +66,95 @@
 
 * C++20 for the Linux platform.
 * MacOS C++20 for the Apple platform.
+
+Working on large features
+=========================
+
+For features in a not yet ratified C++ Standard libc++ makes no guarantees
+about the implementation status nor the ABI stability. After the C++ Standard
+is ratified libc++ promises a conforming ABI stable implementation. When
+working on a large new feature in the ratified version of the C++ Standard that
+can't be finished before the next release branch is created, we can't honor
+this promise. Another reason for not being able to promise ABI stability
+happens when the C++ Standard committee retroactively accepts ABI breaking
+papers as defect reports against the ratified C++ Standard.
+
+When working on these features it should be possible for libc++ vendors to
+disable these incomplete features, so they can promise ABI stability to their
+customers.  This is done by the CMake option
+``LIBCXX_ENABLE_INCOMPLETE_FEATURES``. When start working on a large feature
+the following steps are required to guard the new library with the CMake
+option.
+
+* ``CMakeLists.txt`` add
+
+  .. code-block:: cmake
+
+    config_define_if_not(LIBCXX_ENABLE_INCOMPLETE_FEATURES _LIBCPP_HAS_NO_INCOMPLETE_FOO)
+
+* ``libcxx/include/__config_site.in`` add
+
+  .. code-block:: c++
+
+    #cmakedefine _LIBCPP_HAS_NO_INCOMPLETE_FOO
+
+* ``include/foo`` the contents of the file should be guarded in an ``ifdef``
+  and always include ``<version>``
+
+  .. code-block:: c++
+
+    #ifndef _LIBCPP_FOO
+    #define _LIBCPP_FOO
+
+    // Make sure all feature tests macros are always available.
+    #include <version>
+    // Only enable the contents of the header when libc++ was build with LIBCXX_ENABLE_INCOMPLETE_FEATURES enabled
+    #if !defined(_LIBCPP_HAS_NO_INCOMPLETE_FOO)
+
+    ...
+
+    #endif // !defined(_LIBCPP_HAS_NO_INCOMPLETE_FO0)
+    #endif // _LIBCPP_FOO
+
+* ``src/CMakeLists.txt`` when the library has a file ``foo.cpp`` it should only
+  be added when ``LIBCXX_ENABLE_INCOMPLETE_FEATURES`` is enabled
+
+  .. code-block:: cmake
+
+    if(LIBCXX_ENABLE_INCOMPLETE_FEATURES)
+      list(APPEND LIBCXX_SOURCES
+        foo.cpp
+      )
+    endif()
+
+* ``utils/generate_feature_test_macro_components.py`` add to ``lit_markup``
+
+  .. code-block:: python
+
+    "foo": ["UNSUPPORTED: libcpp-has-no-incomplete-foo"],
+
+* ``utils/generate_header_inclusion_tests.py`` add to ``lit_markup``
+
+  .. code-block:: python
+
+    "foo": ["UNSUPPORTED: libcpp-has-no-incomplete-foo"],
+
+* ``utils/generate_header_tests.py`` add to ``header_markup``
+
+  .. code-block:: python
+
+    "foo": ["ifndef _LIBCPP_HAS_NO_INCOMPLETE_FOO"],
+
+* ``utils/libcxx/test/features.py`` add to ``macros``
+
+  .. code-block:: python
+
+    '_LIBCPP_HAS_NO_INCOMPLETE_FOO': 'libcpp-has-no-incomplete-foo',
+
+* All tests that include ``<foo>`` should contain
+
+  .. code-block:: c++
+
+    // UNSUPPORTED: libcpp-has-no-incomplete-foo
+
+Once the library is complete these changes and guards should be removed.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D107596.364582.patch
Type: text/x-patch
Size: 3230 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20210805/f8c7a5d1/attachment.bin>