2016-12-28 12:58:52 +08:00
|
|
|
==========
|
|
|
|
Debug Mode
|
|
|
|
==========
|
|
|
|
|
|
|
|
.. contents::
|
2017-02-05 09:16:25 +08:00
|
|
|
:local:
|
2016-12-28 12:58:52 +08:00
|
|
|
|
|
|
|
.. _using-debug-mode:
|
|
|
|
|
|
|
|
Using Debug Mode
|
|
|
|
================
|
|
|
|
|
|
|
|
Libc++ provides a debug mode that enables assertions meant to detect incorrect
|
|
|
|
usage of the standard library. By default these assertions are disabled but
|
|
|
|
they can be enabled using the ``_LIBCPP_DEBUG`` macro.
|
|
|
|
|
|
|
|
**_LIBCPP_DEBUG** Macro
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
**_LIBCPP_DEBUG**:
|
|
|
|
This macro is used to enable assertions and iterator debugging checks within
|
|
|
|
libc++. By default it is undefined.
|
|
|
|
|
|
|
|
**Values**: ``0``, ``1``
|
|
|
|
|
|
|
|
Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
|
|
|
|
assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
|
|
|
|
which provides additional assertions about the validity of iterators used by
|
|
|
|
the program.
|
|
|
|
|
2019-06-08 12:59:41 +08:00
|
|
|
Note that this option has no effect on libc++'s ABI; but it does have broad
|
|
|
|
ODR implications. Users should compile their whole program at the same
|
|
|
|
debugging level.
|
2016-12-28 12:58:52 +08:00
|
|
|
|
|
|
|
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
|
2019-06-08 12:59:41 +08:00
|
|
|
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.
|
2016-12-28 12:58:52 +08:00
|
|
|
|
|
|
|
.. code-block:: cpp
|
|
|
|
|
|
|
|
#define _LIBCPP_DEBUG 1
|
|
|
|
#include <string>
|
2019-06-08 12:59:41 +08:00
|
|
|
void my_handler(std::__libcpp_debug_info const&);
|
Support tests in freestanding
Summary:
Freestanding is *weird*. The standard allows it to differ in a bunch of odd
manners from regular C++, and the committee would like to improve that
situation. I'd like to make libc++ behave better with what freestanding should
be, so that it can be a tool we use in improving the standard. To do that we
need to try stuff out, both with "freestanding the language mode" and
"freestanding the library subset".
Let's start with the super basic: run the libc++ tests in freestanding, using
clang as the compiler, and see what works. The easiest hack to do this:
In utils/libcxx/test/config.py add:
self.cxx.compile_flags += ['-ffreestanding']
Run the tests and they all fail.
Why? Because in freestanding `main` isn't special. This "not special" property
has two effects: main doesn't get mangled, and main isn't allowed to omit its
`return` statement. The first means main gets mangled and the linker can't
create a valid executable for us to test. The second means we spew out warnings
(ew) and the compiler doesn't insert the `return` we omitted, and main just
falls of the end and does whatever undefined behavior (if you're luck, ud2
leading to non-zero return code).
Let's start my work with the basics. This patch changes all libc++ tests to
declare `main` as `int main(int, char**` so it mangles consistently (enabling us
to declare another `extern "C"` main for freestanding which calls the mangled
one), and adds `return 0;` to all places where it was missing. This touches 6124
files, and I apologize.
The former was done with The Magic Of Sed.
The later was done with a (not quite correct but decent) clang tool:
https://gist.github.com/jfbastien/793819ff360baa845483dde81170feed
This works for most tests, though I did have to adjust a few places when e.g.
the test runs with `-x c`, macros are used for main (such as for the filesystem
tests), etc.
Once this is in we can create a freestanding bot which will prevent further
regressions. After that, we can start the real work of supporting C++
freestanding fairly well in libc++.
<rdar://problem/47754795>
Reviewers: ldionne, mclow.lists, EricWF
Subscribers: christof, jkorous, dexonsmith, arphaman, miyuki, libcxx-commits
Differential Revision: https://reviews.llvm.org/D57624
llvm-svn: 353086
2019-02-05 04:31:13 +08:00
|
|
|
int main(int, char**) {
|
2019-06-08 12:59:41 +08:00
|
|
|
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
|
2016-12-28 12:58:52 +08:00
|
|
|
}
|
|
|
|
|
|
|
|
Debug Mode Checks
|
|
|
|
=================
|
|
|
|
|
|
|
|
Libc++'s debug mode offers two levels of checking. The first enables various
|
|
|
|
precondition checks throughout libc++. The second additionally enables
|
|
|
|
"iterator debugging" which checks the validity of iterators used by the program.
|
|
|
|
|
|
|
|
Basic Checks
|
|
|
|
============
|
|
|
|
|
|
|
|
These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
|
|
|
|
|
|
|
|
The following checks are enabled by ``_LIBCPP_DEBUG``:
|
|
|
|
|
|
|
|
* FIXME: Update this list
|
|
|
|
|
|
|
|
Iterator Debugging Checks
|
|
|
|
=========================
|
|
|
|
|
|
|
|
These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
|
|
|
|
|
|
|
|
The following containers and STL 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.
|