compilers: cpp: wire up stdlib assertions

None of the options set here affect ABI and are intended for detecting constraint
violations.

For GCC, we simply need to set -D_GLIBCXX_ASSERTIONS.

For Clang, the situation is far more complicated:
* LLVM 18 uses a 'hardened mode' (https://libcxx.llvm.org/Hardening.html).
  There are several levels of severity available here. I've chosen
  _LIBCPP_HARDENING_MODE_EXTENSIVE as the strongest-but-one. The strongest
  one (_DEBUG) doesn't affect ABI still but is reserved for stldebug.

* LLVM 15 uses a similar approach to libstdc++ called '_LIBCPP_ENABLE_ASSERTIONS'

Note that LLVM 17 while in development had fully deprecated _LIBCPP_ENABLE_ASSERTIONS
in favour of hardened, but changed its mind last-minute: https://discourse.llvm.org/t/rfc-hardening-in-libc/73925/4.

Signed-off-by: Sam James <sam@gentoo.org>
Signed-off-by: Eli Schwartz <eschwartz93@gmail.com>

1 files changed, 10 insertions, 0 deletions

diff --git a/docs/markdown/snippets/cpp-debug.md b/docs/markdown/snippets/cpp-debug.md
new file mode 100644
index 000000000..2a62b9399
--- /dev/null
+++ b/docs/markdown/snippets/cpp-debug.md
@@ -0,0 +1,10 @@
+## `ndebug` setting now controls C++ stdlib assertions
+
+The `ndebug` setting, if disabled, now passes preprocessor defines to enable
+debugging assertions within the C++ standard library.
+
+For GCC, `-D_GLIBCXX_ASSERTIONS=1` is set.
+
+For Clang, `-D_GLIBCXX_ASSERTIONS=1` is set to cover libstdc++ usage,
+and `-D_LIBCPP_HARDENING_MODE=_LIBCPP_HARDENING_MODE_EXTENSIVE` or
+`-D_LIBCPP_ENABLE_ASSERTIONS=1` is used depending on the Clang version.