[libc++] Make the Debug mode a configuration-time only option
The debug mode has been broken pretty much ever since it was shipped
because it was possible to enable the debug mode in user code without
actually enabling it in the dylib, leading to ODR violations that
caused various kinds of failures.
This commit makes the debug mode a knob that is configured when
building the library and which can't be changed afterwards. This is
less flexible for users, however it will actually work as intended
and it will allow us, in the future, to add various kinds of checks
that do not assume the same ABI as the normal library. Furthermore,
this will make the debug mode more robust, which means that vendors
might be more tempted to support it properly, which hasn't been the
case with the current debug mode.
This patch shouldn't break any user code, except folks who are building
against a library that doesn't have the debug mode enabled and who try
to enable the debug mode in their code. Such users will get a compile-time
error explaining that this configuration isn't supported anymore.
In the future, we should further increase the granularity of the debug
mode checks so that we can cherry-pick which checks to enable, like we
do for unspecified behavior randomization.
Differential Revision: https://reviews.llvm.org/D122941
NOKEYCHECK=True
GitOrigin-RevId: f3966eaf869b7bdd9113ab9d5b78469eb0f5f028
diff --git a/docs/DesignDocs/DebugMode.rst b/docs/DesignDocs/DebugMode.rst
index b792251..9d0e78e 100644
--- a/docs/DesignDocs/DebugMode.rst
+++ b/docs/DesignDocs/DebugMode.rst
@@ -12,35 +12,33 @@
Libc++ provides a debug mode that enables special debugging checks meant to detect
incorrect usage of the standard library. These checks are disabled by default, but
-they can be enabled using the ``_LIBCPP_DEBUG`` macro.
+they can be enabled by vendors when building the library by using ``LIBCXX_ENABLE_DEBUG_MODE``.
-Note that using the debug mode discussed in this document requires that the library
-has been compiled with support for the debug mode (see ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT``).
+Since the debug mode has ABI implications, users should compile their whole program,
+including any dependent libraries, against a Standard library configured identically
+with respect to the debug mode. In other words, they should not mix code built against
+a Standard library with the debug mode enabled with code built against a Standard library
+where the debug mode is disabled.
-Also note that while the debug mode has no effect on libc++'s ABI, it does have broad ODR
-implications. Users should compile their whole program at the same debugging level.
+Furthermore, users should not rely on a stable ABI being provided when the debug mode is
+enabled -- we reserve the right to change the ABI at any time. If you need a stable ABI
+and still want some level of hardening, you should look into enabling :ref:`assertions <assertions-mode>`
+instead.
-The various levels of checking provided by the debug mode follow.
+The debug mode provides various checks to aid application debugging.
-No debugging checks (``_LIBCPP_DEBUG`` not defined)
----------------------------------------------------
-When ``_LIBCPP_DEBUG`` is not defined, there are no debugging checks performed by
-the library. This is the default.
-
-Comparator consistency checks (``_LIBCPP_DEBUG == 1``)
-------------------------------------------------------
+Comparator consistency checks
+-----------------------------
Libc++ provides some checks for the consistency of comparators passed to algorithms. Specifically,
many algorithms such as ``binary_search``, ``merge``, ``next_permutation``, and ``sort``, wrap the
user-provided comparator to assert that `!comp(y, x)` whenever `comp(x, y)`. This can cause the
user-provided comparator to be evaluated up to twice as many times as it would be without the
debug mode, and causes the library to violate some of the Standard's complexity clauses.
-Iterator debugging checks (``_LIBCPP_DEBUG == 1``)
---------------------------------------------------
-Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging", which provides
-additional assertions about the validity of iterators used by the program.
-
-The following containers and classes support iterator debugging:
+Iterator debugging checks
+-------------------------
+The library contains various assertions to check the validity of iterators used
+by the program. The following containers and classes support iterator debugging:
- ``std::string``
- ``std::vector<T>`` (``T != bool``)
@@ -53,34 +51,11 @@
The remaining containers do not currently support iterator debugging.
Patches welcome.
-Randomizing Unspecified Behavior (``_LIBCPP_DEBUG == 1``)
----------------------------------------------------------
-This also enables the randomization of unspecified behavior, for
-example, for equal elements in ``std::sort`` or randomizing both parts of
-the partition after ``std::nth_element`` call. This effort helps you to migrate
-to potential future faster versions of these algorithms and deflake your tests
-which depend on such behavior. To fix the seed, use
-``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed`` definition.
-
-Handling Assertion Failures
-===========================
-When a debug assertion fails the assertion handler is called via the
-``std::__libcpp_debug_function`` function pointer. It is possible to override
-this function pointer using a different handler function. Libc++ provides a
-the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the
-program. The handler may not return. Libc++ can be changed to use a custom
-assertion handler as follows.
-
-.. code-block:: cpp
-
- #define _LIBCPP_DEBUG 1
- #include <string>
- void my_handler(std::__libcpp_debug_info const&);
- int main(int, char**) {
- std::__libcpp_debug_function = &my_handler;
-
- std::string::iterator bad_it;
- std::string str("hello world");
- str.insert(bad_it, '!'); // causes debug assertion
- // control flow doesn't return
- }
+Randomizing unspecified behavior
+--------------------------------
+The library supports the randomization of unspecified behavior. For example, randomizing
+the relative order of equal elements in ``std::sort`` or randomizing both parts of the
+partition after calling ``std::nth_element``. This effort helps migrating to potential
+future faster versions of these algorithms that might not have the exact same behavior.
+In particular, it makes it easier to deflake tests that depend on unspecified behavior.
+A seed can be used to make such failures reproducible: use ``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed``.
diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index c21d1f9..cb4691f 100644
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -113,6 +113,13 @@
- ``vector<bool>::const_reference``, ``vector<bool>::const_iterator::reference``
and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI.
+- The ``_LIBCPP_DEBUG`` macro is not supported anymore. It will be honoured until
+ LLVM 16, and then it will be an error to define that macro. To enable basic
+ assertions (previously ``_LIBCPP_DEBUG=0``), please use ``_LIBCPP_ENABLE_ASSERTIONS=1``.
+ To enable the debug mode (previously ``_LIBCPP_DEBUG=1|2``), please ensure that
+ the library has been built with support for the debug mode, and it will be
+ enabled automatically (no need to define ``_LIBCPP_DEBUG``).
+
ABI Changes
-----------
@@ -168,3 +175,7 @@
configuration and isn't supported by one of the configurations in ``libcxx/test/configs``,
``libcxxabi/test/configs`` or ``libunwind/test/configs``, please move to one of those
configurations or define your own.
+
+- The ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT`` CMake configuration is not supported anymore. If you
+ were disabling support for the debug mode with that flag, please use ``LIBCXX_ENABLE_BACKWARDS_COMPATIBILITY_DEBUG_MODE_SYMBOLS=OFF``
+ instead.
diff --git a/docs/TestingLibcxx.rst b/docs/TestingLibcxx.rst
index b5c7ae8..04ed531 100644
--- a/docs/TestingLibcxx.rst
+++ b/docs/TestingLibcxx.rst
@@ -158,13 +158,6 @@
still be used to specify the path of the library to link to and run against,
respectively.
-.. option:: debug_level=<level>
-
- **Values**: 0, 1
-
- Enable the use of debug mode. Level 0 enables assertions and level 1 enables
- assertions and debugging of iterator misuse.
-
.. option:: use_sanitizer=<sanitizer name>
**Values**: Memory, MemoryWithOrigins, Address, Undefined
diff --git a/docs/UsingLibcxx.rst b/docs/UsingLibcxx.rst
index 0d7e3a9..1f46f0a 100644
--- a/docs/UsingLibcxx.rst
+++ b/docs/UsingLibcxx.rst
@@ -214,9 +214,6 @@
or disable extended libc++ behavior, including enabling "debug mode" or
thread safety annotations.
-**_LIBCPP_DEBUG**:
- See :ref:`using-debug-mode` for more information.
-
**_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
This macro is used to enable -Wthread-safety annotations on libc++'s
``std::mutex`` and ``std::lock_guard``. By default, these annotations are