Include info on headers in the readme, and a couple other tweaks

This commit is contained in:
Jeremy Rifkin 2024-10-06 14:54:58 -05:00
parent 0d2cb217bf
commit 2d5842164b
No known key found for this signature in database
GPG Key ID: 19AA8270105E8EB4

View File

@ -34,9 +34,11 @@ Cpptrace also has a C API, docs [here](docs/c-api.md).
- [Performance](#performance) - [Performance](#performance)
- [Traced Exception Objects](#traced-exception-objects) - [Traced Exception Objects](#traced-exception-objects)
- [Wrapping std::exceptions](#wrapping-stdexceptions) - [Wrapping std::exceptions](#wrapping-stdexceptions)
- [Exception handling with cpptrace](#exception-handling-with-cpptrace) - [Exception handling with cpptrace exception objects](#exception-handling-with-cpptrace-exception-objects)
- [Terminate Handling](#terminate-handling)
- [Signal-Safe Tracing](#signal-safe-tracing) - [Signal-Safe Tracing](#signal-safe-tracing)
- [Utility Types](#utility-types) - [Utility Types](#utility-types)
- [Headers](#headers)
- [Supported Debug Formats](#supported-debug-formats) - [Supported Debug Formats](#supported-debug-formats)
- [How to Include The Library](#how-to-include-the-library) - [How to Include The Library](#how-to-include-the-library)
- [CMake FetchContent](#cmake-fetchcontent) - [CMake FetchContent](#cmake-fetchcontent)
@ -633,7 +635,7 @@ CPPTRACE_WRAP_BLOCK(
std::cout<<CPPTRACE_WRAP(foo.at(12))<<std::endl; std::cout<<CPPTRACE_WRAP(foo.at(12))<<std::endl;
``` ```
### Exception handling with cpptrace ### Exception handling with cpptrace exception objects
> [!NOTE] > [!NOTE]
> This section pertains to cpptrace traced exception objects and not the mechanism for collecting > This section pertains to cpptrace traced exception objects and not the mechanism for collecting
@ -653,10 +655,12 @@ try {
} }
``` ```
Additionally cpptrace provides a custom `std::terminate` handler that prints a stack trace from a cpptrace exception and otherwise behaves like the normal terminate handler and prints the stack trace involved in reaching `std::terminate`. ## Terminate Handling
The stack trace to `std::terminate` may be helpful or it may not, it depends on the implementation, but often if an
implementation can't find an appropriate `catch` while unwinding it will jump directly to `std::terminate` giving Cpptrace provides a custom `std::terminate` handler that prints stacktraces while otherwise behaving like the normal
good information. `std::terminate` handler. If a cpptrace exception object reaches `std::terminate` the trace from that exception is
printed, otherwise a stack trace is generated at the point of the terminate handler. Often `std::terminate` is called
directly without unwinding so the trace is preserved.
To register this custom handler: To register this custom handler:
@ -768,19 +772,31 @@ namespace cpptrace {
} }
``` ```
## Headers
Cpptrace provides a handful of headers to make inclusion more minimal.
| Header | Contents |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpptrace/forward.hpp` | `cpptrace::frame_ptr` and a few trace class forward declarations |
| `cpptrace/basic.hpp` | Definitions for trace classes and the basic tracing APIs ([Stack Traces](#stack-traces), [Object Traces](#object-traces), [Raw Traces](#raw-traces), and [Signal-Safe Tracing](#signal-safe-tracing)) |
| `cpptrace/exceptions.hpp` | [Traced Exception Objects](#traced-exception-objects) and related utilities ([Wrapping std::exceptions](#wrapping-stdexceptions)) |
| `cpptrace/from_current.hpp` | [Traces From All Exceptions](#traces-from-all-exceptions) |
| `cpptrace/io.hpp` | `operator<<` overloads for `std::ostream` and `std::formatter`s |
| `cpptrace/utils.hpp` | Utility functions, configuration functions, and terminate utilities ([Utilities](#utilities), [Configuration](#configuration), and [Terminate Handling](#terminate-handling)) |
The main cpptrace header is `cpptrace/cpptrace.hpp` which includes everything other than `from_current.hpp`.
# Supported Debug Formats # Supported Debug Formats
| Format | Supported | | Format | Supported |
| --------------------------------- | --------- | | ---------------------------- | --------- |
| DWARF in binary | ✔️ | | DWARF in binary | ✔️ |
| GNU debug link | ️️✔️ | | GNU debug link | ️️✔️ |
| Split dwarf (debug fission) | ✔️* | | Split dwarf (debug fission) | ✔️ |
| DWARF in dSYM | ✔️ | | DWARF in dSYM | ✔️ |
| DWARF via Mach-O debug map | ✔️ | | DWARF via Mach-O debug map | ✔️ |
| Windows debug symbols in PDB | ✔️ | | Windows debug symbols in PDB | ✔️ |
*There seem to be a couple issues upstream with libdwarf however they will hopefully be resolved soon.
DWARF5 added DWARF package files. As far as I can tell no compiler implements these yet. DWARF5 added DWARF package files. As far as I can tell no compiler implements these yet.
# How to Include The Library # How to Include The Library