mirror of
https://github.com/llvm/llvm-project.git
synced 2025-04-28 11:26:07 +00:00
f3966eaf86
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
62 lines
2.7 KiB
ReStructuredText
62 lines
2.7 KiB
ReStructuredText
==========
|
|
Debug Mode
|
|
==========
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. _using-debug-mode:
|
|
|
|
Using the debug mode
|
|
====================
|
|
|
|
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 by vendors when building the library by using ``LIBCXX_ENABLE_DEBUG_MODE``.
|
|
|
|
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.
|
|
|
|
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 debug mode provides various checks to aid application debugging.
|
|
|
|
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
|
|
-------------------------
|
|
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``)
|
|
- ``std::list``
|
|
- ``std::unordered_map``
|
|
- ``std::unordered_multimap``
|
|
- ``std::unordered_set``
|
|
- ``std::unordered_multiset``
|
|
|
|
The remaining containers do not currently support iterator debugging.
|
|
Patches welcome.
|
|
|
|
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``.
|