[libcxx-commits] [PATCH] D99290: [libc++] Update contributor documentation.

[Mark de Wever via Phabricator via libcxx-commits]

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

The document has the following updates:

- Rename 'feature test' to 'feature-test', the latter is the spelling used in the Standard.
- Improve documentation regarding how to add new feature-test macros in `generate_feature_test_macro_components.py`. Recently there was some confusion regarding the fields `depends` and `internal_depends`.
- Add information how an ABI list can be downloaded from Buildkite.

@EricWF I would be grateful if you can have a look at the changes
regarding the `generate_feature_test_macro_components.py` documentation
since you wrote the original version.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D99290

Files:
  libcxx/docs/Contributing.rst


Index: libcxx/docs/Contributing.rst
===================================================================
--- libcxx/docs/Contributing.rst
+++ libcxx/docs/Contributing.rst
@@ -33,12 +33,42 @@
 2. Update the ``include/__libcpp_version`` file
 3. Update the version number in ``docs/conf.py``
 
-Modifying feature test macros
+Modifying feature-test macros
 =============================
 
-When adding or updating feature test macros, you should update the corresponding tests.
+When adding or updating feature-test macros, you should update the corresponding tests.
 To do that, modify ``feature_test_macros`` table in the script ``utils/generate_feature_test_macro_components.py``, run it, and commit updated files.
 
+================  ==============================================================
+Field             Description
+================  ==============================================================
+name              The name of the feature-test macro.
+values            A list of tuples. One tuple contains a C++ version and the
+                  value of the feature-test marco for that C++ version.
+headers           An array with the headers that should provide the
+                  feature-test macro.
+depends           An optional string field. When this field is provided
+                  ``internal_depends`` must also be provided. The field
+                  contains the dependencies for the feature. It should contain
+                  the dependency on:
+
+                  * a compiler version,
+                  * a compiler feature-test macro,
+                  * a CMake generated define, or
+                  * a macro defined in ``include/__availability``.
+
+                  It shall not depend on a macro defined in ``include/__config``.
+internal_depends  An optional string field. When this field is provided
+                  ``depends`` must also be provided. It contains the dependency:
+
+                  * when available, a macro defined in ``include/__config``,
+                  * otherwise the same as ``depends``.
+unimplemented     An optional Boolean field with the value ``True``. This field
+                  is only used when a feature isn't fully implemented. Once
+                  fully implemented the field shall be removed.
+================  ==============================================================
+
+
 Adding a new header TODO
 ========================
 
@@ -55,3 +85,12 @@
 When exporting new symbols from libc++, one must update the ABI lists located in ``lib/abi``.
 To test whether the lists are up-to-date, please run the target ``check-cxx-abilist``.
 To regenerate the lists, use the target ``generate-cxx-abilist``.
+The ABI lists must be updated all supported platforms; currently Linux and Apple.
+If you don't have access to one of these platforms an updated list can be
+downloaded from the failed build at
+`Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__.
+Look for the failed build and select the ``artifacts`` tab. There download the
+abilist for the plafform, e.g.:
+
+* C++20 for the Linux platform.
+* MacOS C++20 for the Apple platform.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D99290.333080.patch
Type: text/x-patch
Size: 3156 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/libcxx-commits/attachments/20210324/82c9ceac/attachment.bin>