1==========
2Debug Mode
3==========
4
5.. contents::
6   :local:
7
8.. _using-debug-mode:
9
10Using the debug mode
11====================
12
13Libc++ provides a debug mode that enables special debugging checks meant to detect
14incorrect usage of the standard library. These checks are disabled by default, but
15they can be enabled by vendors when building the library by using ``LIBCXX_ENABLE_DEBUG_MODE``.
16
17Since the debug mode has ABI implications, users should compile their whole program,
18including any dependent libraries, against a Standard library configured identically
19with respect to the debug mode. In other words, they should not mix code built against
20a Standard library with the debug mode enabled with code built against a Standard library
21where the debug mode is disabled.
22
23Furthermore, users should not rely on a stable ABI being provided when the debug mode is
24enabled -- we reserve the right to change the ABI at any time. If you need a stable ABI
25and still want some level of hardening, you should look into enabling :ref:`assertions <assertions-mode>`
26instead.
27
28The debug mode provides various checks to aid application debugging.
29
30Comparator consistency checks
31-----------------------------
32Libc++ provides some checks for the consistency of comparators passed to algorithms. Specifically,
33many algorithms such as ``binary_search``, ``merge``, ``next_permutation``, and ``sort``, wrap the
34user-provided comparator to assert that `!comp(y, x)` whenever `comp(x, y)`. This can cause the
35user-provided comparator to be evaluated up to twice as many times as it would be without the
36debug mode, and causes the library to violate some of the Standard's complexity clauses.
37
38Iterator debugging checks
39-------------------------
40The library contains various assertions to check the validity of iterators used
41by the program. The following containers and classes support iterator debugging:
42
43- ``std::string``
44- ``std::vector<T>`` (``T != bool``)
45- ``std::list``
46- ``std::unordered_map``
47- ``std::unordered_multimap``
48- ``std::unordered_set``
49- ``std::unordered_multiset``
50
51The remaining containers do not currently support iterator debugging.
52Patches welcome.
53
54Randomizing unspecified behavior
55--------------------------------
56The library supports the randomization of unspecified behavior. For example, randomizing
57the relative order of equal elements in ``std::sort`` or randomizing both parts of the
58partition after calling ``std::nth_element``. This effort helps migrating to potential
59future faster versions of these algorithms that might not have the exact same behavior.
60In particular, it makes it easier to deflake tests that depend on unspecified behavior.
61A seed can be used to make such failures reproducible: use ``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed``.
62