mirror of
https://github.com/Gericom/teak-llvm.git
synced 2025-06-19 19:45:40 -04:00
2df59c5068
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
101 lines
3.0 KiB
ReStructuredText
101 lines
3.0 KiB
ReStructuredText
==========
|
|
Debug Mode
|
|
==========
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. _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.
|
|
|
|
Note that this option has no effect on libc++'s ABI
|
|
|
|
**_LIBCPP_DEBUG_USE_EXCEPTIONS**:
|
|
When this macro is defined ``_LIBCPP_ASSERT`` failures throw
|
|
``__libcpp_debug_exception`` instead of aborting. Additionally this macro
|
|
disables exception specifications on functions containing ``_LIBCPP_ASSERT``
|
|
checks. This allows assertion failures to correctly throw through these
|
|
functions.
|
|
|
|
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 two
|
|
different assertion handlers, the default handler
|
|
``std::__libcpp_abort_debug_handler`` which aborts the program, and
|
|
``std::__libcpp_throw_debug_handler`` which throws an instance of
|
|
``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing
|
|
assertion handler as follows:
|
|
|
|
.. code-block:: cpp
|
|
|
|
#define _LIBCPP_DEBUG 1
|
|
#include <string>
|
|
int main(int, char**) {
|
|
std::__libcpp_debug_function = std::__libcpp_throw_debug_function;
|
|
try {
|
|
std::string::iterator bad_it;
|
|
std::string str("hello world");
|
|
str.insert(bad_it, '!'); // causes debug assertion
|
|
} catch (std::__libcpp_debug_exception const&) {
|
|
return EXIT_SUCCESS;
|
|
}
|
|
return EXIT_FAILURE;
|
|
}
|
|
|
|
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.
|