[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,199 @@
+=======================
+libc++'s ABI Guarantees
+=======================
+
+libc++ provides multiple types 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 fields as well as what options exist for users and 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.
+
+
----------------
ldionne wrote:

Here's another bit of information that might be worth including: the notion that each ABI configuration (i.e. each set of ABI macros) gives rise to a stable ABI. I have a local patch where I had some documentation that touched on that, let me paste it here so you can cherry-pick from it:

```
//
// ABI configuration macros
// ========================
//
// Each macro defined here can be overridden by setting it to 1/0 inside __config_site. These macros define the
// ABI configuration of the library, which is a stable property once set. This means that each combination of
// ABI macros gives rise to an ABI that is stable across all supported "usage scenarios" of the library
// (-fno-exceptions, compilers, standard versions, etc).
//
// If a usage scenario makes it impossible to honor a specific ABI configuration (such as the implementation
// requiring a specific compiler or standard mode), it should be a hard error at compile-time to try enabling
// that ABI configuration under that usage scenario. This ensures that if an ABI configuration is opted-into,
// that ABI cannot be silently broken under some usage scenarios.
```

Here's something that was also part of this documentation but isn't implemented right now. I'm pasting it just cause I think it's interesting and we should eventually move towards that, but it doesn't belong in this patch:

```
// Each ABI configuration macro also defines a "signature element" which is used to encode the fact that this
// ABI macro is active and distinguish it from other configurations of the library. Amongst other things, this
// is then encoded in the inline namespace used by the library.
//
// Defining new ABI configurations
// -------------------------------
// First, think about whether the ABI configuration can be implemented under all supported usage scenarios. If
// that is not the case, carefully consider if that ABI configuration is still generally useful, and if so, make
// sure to trigger an error at compile-time when the ABI configuration cannot be honored.
//
// Then, define a macro with a descriptive name and default it to 0 (aka disabled). Also select an ABI signature
// element that will be encoded in the inline namespace when that ABI configuration is active. We recommend using
// single characters in sequence to keep symbol names short.
//
// Finally, make sure to add the new ABI configuration macro to the definition of the ABI signature. Look for the
// definition of the _LIBCPP_ABI_SIGNATURE macro.
```

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