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 bounds checking 39------------------------ 40The library provides iterators that ensure they are within the bounds of their container when dereferenced. 41Arithmetic can be performed on these iterators to create out-of-bounds iterators, but they cannot be dereferenced 42when out-of-bounds. The following classes currently provide iterators that have bounds checking: 43 44- ``std::string`` 45- ``std::vector<T>`` (``T != bool``) 46- ``std::span`` 47 48.. TODO: Add support for iterator bounds checking in ``std::string_view`` and ``std::array`` 49 50Iterator ownership checking 51--------------------------- 52The library provides iterator ownership checking, which allows catching cases where e.g. 53an iterator from container ``X`` is used as a position to insert into container ``Y``. 54The following classes support iterator ownership checking: 55 56- ``std::string`` 57- ``std::vector<T>`` (``T != bool``) 58- ``std::list`` 59- ``std::unordered_map`` 60- ``std::unordered_multimap`` 61- ``std::unordered_set`` 62- ``std::unordered_multiset`` 63 64Randomizing unspecified behavior 65-------------------------------- 66The library supports the randomization of unspecified behavior. For example, randomizing 67the relative order of equal elements in ``std::sort`` or randomizing both parts of the 68partition after calling ``std::nth_element``. This effort helps migrating to potential 69future faster versions of these algorithms that might not have the exact same behavior. 70In particular, it makes it easier to deflake tests that depend on unspecified behavior. 71A seed can be used to make such failures reproducible: use ``_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=seed``. 72