[libc++] Introduce a compile-time mechanism to override __libcpp_verbose_abort

[ldionne]

Summary

This changes the mechanism for verbose termination (again!) to make it
support compile-time customization in addition to link-time customization,
which is important for users who need fine-grained control over what code
gets generated around sites that call the verbose termination handler.

This concern had been raised to me both privately by prospecting users
and in https://llvm.org/D140944, so I think it is clearly worth fixing.

We still support _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED for
a limited time since the same functionality can be achieved by overriding
the _LIBCPP_VERBOSE_ABORT macro.

[ldionne]

Adding vendors since this is a pretty fundamental piece of the library and I'd like to know if other folks have points that have not been considered yet in this design (and re-design) of the mechanism.

[vitalybuka]

Thanks, LGTM!

[MaskRay]

The macro use of _LIBCPP_VERBOSE_ABORT looks great. It supports both the compile-time and link-time needs (users who want __builtin_abort (they can use a SIGABRT handler to give users a backtrace) and users who what to customize the message).

[vitalybuka]

@thakis @hans FYI
_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED is used in Chromium
https://source.chromium.org/chromium/chromium/src/+/main:build/config/c++/BUILD.gn;l=108?q=_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED&ss=chromium

libcxx/include/__verbose_abort

41

@thakis @hans FYI
_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED is used in Chromium
https://source.chromium.org/chromium/chromium/src/+/main:build/config/c++/BUILD.gn;l=108?q=_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED&ss=chromium

[Mordante]

libcxx/docs/ReleaseNotes.rst

143

Since we add this so closely to the LLVM 16 release, would it be better to remove in LLVM 18?

[vitalybuka]

@ldionne Any guess when this can be landed?

[ldionne]

Rebase and deprecate in LLVM 18. Sorry folks, I've been hella busy but I'm trying to put this in LLVM 16.

[hans]

libcxx/include/__verbose_abort

41

@ayzhao we should look into switching to _LIBCPP_VERBOSE_ABORT when this lands.

[ldionne]

Fix test in backdeployment

[ldionne]

Try to fix GCC build

libcxx/docs/ReleaseNotes.rst

 ----------------------------------
 - The base template for ``std::char_traits`` has been marked as deprecated and will be removed in LLVM 18. If
   you are using ``std::char_traits`` with types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``,
   ``char32_t`` or a custom character type for which you specialized ``std::char_traits``, your code will stop
   working when we remove the base template. The Standard does not mandate that a base template is provided,
   and such a base template is bound to be incorrect for some types, which could currently cause unexpected
   behavior while going undetected.
 
+- The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro will not be honored anymore in LLVM 18.
+  Please see the updated documentation about the safe libc++ mode and in particular the ``_LIBCPP_VERBOSE_ABORT``
+  macro for details.
+
 API Changes
 -----------
 - The comparison operators on ``thread::id`` are now defined as free-standing
   functions instead of as hidden friends, in conformance with the C++ standard.
   Also see `issue 56187 <https://github.com/llvm/llvm-project/issues/56187>`_.
 
 - ``_LIBCPP_ENABLE_NODISCARD`` and ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17`` are no longer respected.
   Any standards-required ``[[nodiscard]]`` applications in C++20 are now always enabled. Any extended applications

libcxx/docs/UsingLibcxx.rst

 disable them). However, most of the code in libc++ is in the headers, so the user-selected
 value for ``_LIBCPP_ENABLE_ASSERTIONS`` (if any) will usually be respected.
 
 When an assertion fails, the program is aborted through a special verbose termination function. The
 library provides a default function that prints an error message and calls ``std::abort()``. Note
 that this function is provided by the static or shared library, so it is only available when deploying
 to a platform where the compiled library is sufficiently recent. On older platforms, the program will
 terminate in an unspecified unsuccessful manner, but the quality of diagnostics won't be great.
-However, users can also override that function with their own, which can be useful to either provide
-custom behavior or when deploying to an older platform where the default function isn't available.
-
-Replacing the default verbose termination function is done by defining the
-``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro in all translation units of your program
-and defining the following function in exactly one translation unit:
+However, users can also override that mechanism at two different levels. First, the mechanism can be
+overriden at compile-time by defining the ``_LIBCPP_VERBOSE_ABORT(format, args...)`` variadic macro.
+When that macro is defined, it will be called with a format string as the first argument, followed by
+a series of arguments to format using printf-style formatting. Compile-time customization may be
+interesting to get precise control over code generation, however it is also inconvenient to use in
+some cases. Indeed, compile-time customization of the verbose termination function requires that all
+translation units be compiled with a consistent definition for ``_LIBCPP_VERBOSE_ABORT`` to avoid ODR
+violations, which can add complexity in the build system of users.
+
+Otherwise, if compile-time customization is not necessary, link-time customization of the handler is also
+possible, similarly to how replacing ``operator new`` works. This mechanism trades off fine-grained control
+over the call site where the termination is initiated in exchange for more ergonomics. Link-time customization
+is done by simply defining the following function in exactly one translation unit of your program:
 
 .. code-block:: cpp
 
   void __libcpp_verbose_abort(char const* format, ...)
 
 This mechanism is similar to how one can replace the default definition of ``operator new``
 and ``operator delete``. For example:
 

libcxx/include/__assert

 #if _LIBCPP_ENABLE_ASSERTIONS != 0 && _LIBCPP_ENABLE_ASSERTIONS != 1
 # error "_LIBCPP_ENABLE_ASSERTIONS must be set to 0 or 1"
 #endif
 
 #if _LIBCPP_ENABLE_ASSERTIONS
 # define _LIBCPP_ASSERT(expression, message)                                        \
     (__builtin_expect(static_cast<bool>(expression), 1) ?                           \
       (void)0 :                                                                     \
-      ::std::__libcpp_verbose_abort("%s:%d: assertion %s failed: %s", __FILE__, __LINE__, #expression, message))
+      _LIBCPP_VERBOSE_ABORT("%s:%d: assertion %s failed: %s", __FILE__, __LINE__, #expression, message))
 #elif !defined(_LIBCPP_ASSERTIONS_DISABLE_ASSUME) && __has_builtin(__builtin_assume)
 # define _LIBCPP_ASSERT(expression, message)                                        \
     (_LIBCPP_DIAGNOSTIC_PUSH                                                        \
     _LIBCPP_CLANG_DIAGNOSTIC_IGNORED("-Wassume")                                    \
     __builtin_assume(static_cast<bool>(expression))                                 \
     _LIBCPP_DIAGNOSTIC_POP)
 #else
 # define _LIBCPP_ASSERT(expression, message) ((void)0)
 #endif
 
 #endif // _LIBCPP___ASSERT

libcxx/include/__availability

// #   define _LIBCPP_AVAILABILITY_DISABLE_FTM___cpp_lib_semaphore
 
     // This controls the availability of the C++20 format library.
     // The library is in development and not ABI stable yet. P2216 is
     // retroactively accepted in C++20. This paper contains ABI breaking
     // changes.
 #   define _LIBCPP_AVAILABILITY_FORMAT
 // #   define _LIBCPP_AVAILABILITY_DISABLE_FTM___cpp_lib_format
 
-    // This controls whether the default verbose termination function is
-    // provided by the library.
-    //
-    // Note that when users provide their own custom function, it doesn't
-    // matter whether the dylib provides a default function, and the
-    // availability markup can actually give a false positive diagnostic
-    // (it will think that no function is provided, when in reality the
-    // user has provided their own).
-    //
-    // Users can pass -D_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED
-    // to the compiler to tell the library not to define its own verbose abort.
-    // Note that defining this macro but failing to define a custom function
-    // will lead to a load-time error on back-deployment targets, so it should
-    // be avoided.
+    // This controls whether the library claims to provide a default verbose
+    // termination function, and consequently whether the headers will try
+    // to use it when the mechanism isn't overriden at compile-time.
 // #   define _LIBCPP_HAS_NO_VERBOSE_ABORT_IN_LIBRARY
 
 #elif defined(__APPLE__)
 
 #   define _LIBCPP_AVAILABILITY_SHARED_MUTEX                                    \
         __attribute__((availability(macos,strict,introduced=10.12)))            \
         __attribute__((availability(ios,strict,introduced=10.0)))               \
         __attribute__((availability(tvos,strict,introduced=10.0)))              \

libcxx/include/__verbose_abort

 
 #include <__availability>
 #include <__config>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #  pragma GCC system_header
 #endif
 
-// Provide a default implementation of __libcpp_verbose_abort if we know that neither the built
-// library nor the user is providing one. Otherwise, just declare it and use the one from the
-// built library or the one provided by the user.
-//
-// We can't provide a great implementation because it needs to be pretty much
-// dependency-free (this is included everywhere else in the library).
-#if defined(_LIBCPP_HAS_NO_VERBOSE_ABORT_IN_LIBRARY) && !defined(_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED)
-
-_LIBCPP_BEGIN_NAMESPACE_STD
-
-_LIBCPP_NORETURN _LIBCPP_ATTRIBUTE_FORMAT(__printf__, 1, 2) _LIBCPP_HIDE_FROM_ABI inline
-void __libcpp_verbose_abort(const char *, ...) {
-  __builtin_abort();
-}
-
-_LIBCPP_END_NAMESPACE_STD
-
-#else
-
 _LIBCPP_BEGIN_NAMESPACE_STD
 
+// This function should never be called directly from the code -- it should only be called through
+// the _LIBCPP_VERBOSE_ABORT macro.
 _LIBCPP_NORETURN _LIBCPP_OVERRIDABLE_FUNC_VIS _LIBCPP_ATTRIBUTE_FORMAT(__printf__, 1, 2)
 void __libcpp_verbose_abort(const char *__format, ...);
 
-_LIBCPP_END_NAMESPACE_STD
+// _LIBCPP_VERBOSE_ABORT(format, args...)
+//
+// This macro is used to abort the program abnormally while providing additional diagnostic information.
+//
+// The first argument is a printf-style format string, and the remaining arguments are values to format
+// into the format-string. This macro can be customized by users to provide fine-grained control over
+// how verbose termination is triggered.
+//
+// If the user does not supply their own version of the _LIBCPP_VERBOSE_ABORT macro, we pick the default
+// behavior based on whether we know the built library we're running against provides support for the
+// verbose termination handler or not. If it does, we call it. If it doesn't, we call __builtin_abort to
+// make sure that the program terminates but without taking any complex dependencies in this header.
+#if !defined(_LIBCPP_VERBOSE_ABORT)
+
+// Support _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED until LLVM 18, but tell people
+// to move to customizing _LIBCPP_VERBOSE_ABORT instead.
+#  if defined(_LIBCPP_HAS_NO_VERBOSE_ABORT_IN_LIBRARY) && defined(_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED)
+#    undef _LIBCPP_HAS_NO_VERBOSE_ABORT_IN_LIBRARY
+#    warning _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED is deprecated, please customize _LIBCPP_VERBOSE_ABORT instead
+#  endif
 
-#endif
+#  if defined(_LIBCPP_HAS_NO_VERBOSE_ABORT_IN_LIBRARY)
+#    define _LIBCPP_VERBOSE_ABORT(...) __builtin_abort()
+#  else
+#    define _LIBCPP_VERBOSE_ABORT(...) ::std::__libcpp_verbose_abort(__VA_ARGS__)
+#  endif
+#endif // !defined(_LIBCPP_VERBOSE_ABORT)
+
+_LIBCPP_END_NAMESPACE_STD
 
 #endif // _LIBCPP___VERBOSE_ABORT

libcxx/test/libcxx/assertions/customize_verbose_abort.compile-time.pass.cpp

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
-// Make sure that we can enable assertions when we back-deploy to older platforms
-// if we define _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED.
-//
-// Note that this test isn't really different from customize_verbose_abort.pass.cpp when
-// run outside of back-deployment scenarios, but we always want to run this test.
+// This compile-time customization requires cross-file macros, which doesn't work with modules.
+// UNSUPPORTED: modules-build
+
+// Make sure that we can customize the verbose termination function at compile-time by
+// defining _LIBCPP_VERBOSE_ABORT ourselves. Note that this does not have any
+// deployment target requirements.
 
-// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_ASSERTIONS=1 -D_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED
+// ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_ASSERTIONS=1 -D_LIBCPP_VERBOSE_ABORT(...)=my_abort(__VA_ARGS__)
 
 #include <cstdlib>
 
-void std::__libcpp_verbose_abort(char const*, ...) {
+void my_abort(char const*, ...) {
   std::exit(EXIT_SUCCESS);
 }
 
 int main(int, char**) {
   _LIBCPP_ASSERT(false, "message");
   return EXIT_FAILURE;
 }

libcxx/test/libcxx/assertions/customize_verbose_abort.link-time.pass.cpp

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
-// Test that we can set a custom verbose termination function.
+// Test that we can set a custom verbose termination function at link-time.
 
 // ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_ASSERTIONS=1
 
 // We flag uses of the verbose termination function in older dylibs at compile-time to avoid runtime
 // failures when back-deploying.
 // XFAIL: use_system_cxx_lib && target={{.+}}-apple-macosx{{10.9|10.10|10.11|10.12|10.13|10.14|10.15|11.0|12.0}}
 
 #include <cstdlib>

libcxx/test/libcxx/assertions/deprecated-link-time-custom-handler.pass.cpp

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
-// Make sure that we can enable assertions when we back-deploy to older platforms
-// if we define _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED.
-//
-// Note that this test isn't really different from customize_verbose_abort.pass.cpp when
-// run outside of back-deployment scenarios, but we always want to run this test.
+// Make sure that we still support _LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED for folks
+// who customize the verbose termination function at link-time in back-deployment environments.
 
 // ADDITIONAL_COMPILE_FLAGS: -D_LIBCPP_ENABLE_ASSERTIONS=1 -D_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED
 
+// We emit a #warning about the deprecation of this setting, so make sure we don't turn that into an error.
+// ADDITIONAL_COMPILE_FLAGS: -Wno-error
+
 #include <cstdlib>
 
 void std::__libcpp_verbose_abort(char const*, ...) {
   std::exit(EXIT_SUCCESS);
 }
 
 int main(int, char**) {
   _LIBCPP_ASSERT(false, "message");
   return EXIT_FAILURE;
 }

libcxx/test/libcxx/assertions/headers_declare_verbose_abort.sh.cpp

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
-// Test that all public C++ headers define the verbose termination function.
+// Test that all public C++ headers define the verbose termination function, which
+// is required for users to be able to include any public header and then override
+// the function using a strong definition.
 
 // The system-provided <uchar.h> seems to be broken on AIX, which trips up this test.
 // XFAIL: LIBCXX-AIX-FIXME
 
 /*
 BEGIN-SCRIPT
 
 for i, header in enumerate(public_headers):