[libcxx-commits] [libcxx] [libc++] Document our ABI guarantees and what ABI flags exist to modify these guarantees (PR #132615)

[Louis Dionne via libcxx-commits]

================
@@ -0,0 +1,207 @@
+.. _ABIGuarantees:
+
+=======================
+libc++'s ABI Guarantees
+=======================
+
+libc++ provides multiple types of ABI guarantees. These include stability of the layout of structs, the linking of TUs
+built against different versions and configurations of the library, and more. This document describes what guarantees
+libc++ provides in these different areas as well as what options exist for vendors to affect these guarantees.
+
+Note that all of the guarantees listed below come with an asterisk that there may be circumstances where we deem it
+worth it to break that guarantee. These breaks are communicated to vendors by CCing #libcxx-vendors on GitHub. If you
+are a vendor, please ask to be added to that group to be notified about changes that potentially affect you.
+
+ABI flags
+=========
+All the ABI flags listed below can be added to the ``__config_site`` header by the vendor to opt in to an ABI breaking
+change. These flags should never be set by the user. When porting libc++ to a new platform it should be considered by
+the vendor which flags should be enabled, assuming ABI stability is relevant to them. Please contact the libc++ team on
+Discord or through other means to be able to make an informed decision on which flags make sense to enable, and to avoid
+enabling flags which may not be stable. Flags can be enabled via the ``LIBCXX_ABI_DEFINES`` CMake option.
+
+
+Stability of the Layout of Structs
+==================================
+
+The layout of any user-observable struct is kept stable across versions of the library and any options users are allowed
+to change. There are a lot of structs that have internal names, but are none the less observable by users; for example
----------------
ldionne wrote:

```suggestion
The layout of any user-observable struct is kept stable across versions of the library and any user-facing options documented in https://libcxx.llvm.org/UserDocumentation.html#libc-configuration-macros. There are a lot of structs that have internal names, but are none the less observable by users; for example
```

This adds a bit of precision.

https://github.com/llvm/llvm-project/pull/132615