Move FAQ and add entry on standard library symbol linker errors on macos, related to #216
This commit is contained in:
Jeremy Rifkin
parent
e6d55b5e7d
commit
c9dc51aa61
79
README.md
79
README.md
@ -16,9 +16,6 @@ Cpptrace also has a C API, docs [here](docs/c-api.md).
|
||||
|
||||
- [30-Second Overview](#30-second-overview)
|
||||
- [CMake FetchContent Usage](#cmake-fetchcontent-usage)
|
||||
- [FAQ](#faq)
|
||||
- [What about C++23 `<stacktrace>`?](#what-about-c23-stacktrace)
|
||||
- [What does cpptrace have over other C++ stacktrace libraries?](#what-does-cpptrace-have-over-other-c-stacktrace-libraries)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Basic Usage](#basic-usage)
|
||||
- [`namespace cpptrace`](#namespace-cpptrace)
|
||||
@ -57,6 +54,10 @@ Cpptrace also has a C API, docs [here](docs/c-api.md).
|
||||
- [Summary of Library Configurations](#summary-of-library-configurations)
|
||||
- [Testing Methodology](#testing-methodology)
|
||||
- [Notes About the Library](#notes-about-the-library)
|
||||
- [FAQ](#faq)
|
||||
- [What about C++23 `<stacktrace>`?](#what-about-c23-stacktrace)
|
||||
- [What does cpptrace have over other C++ stacktrace libraries?](#what-does-cpptrace-have-over-other-c-stacktrace-libraries)
|
||||
- [I'm getting undefined standard library symbols like `std::__1::basic_string` on MacOS](#im-getting-undefined-standard-library-symbols-like-std__1basic_string-on-macos)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
@ -163,33 +164,6 @@ On macOS it is recommended to generate a `.dSYM` file, see [Platform Logistics](
|
||||
For other ways to use the library, such as through package managers, a system-wide installation, or on a platform
|
||||
without internet access see [How to Include The Library](#how-to-include-the-library) below.
|
||||
|
||||
# FAQ
|
||||
|
||||
## What about C++23 `<stacktrace>`?
|
||||
|
||||
Some day C++23's `<stacktrace>` will be ubiquitous. And maybe one day the msvc implementation will be acceptable.
|
||||
The original motivation for cpptrace was to support projects using older C++ standards and as the library has grown its
|
||||
functionality has extended beyond the standard library's implementation.
|
||||
|
||||
Cpptrace provides functionality beyond what the standard library provides and what implementations provide, such as:
|
||||
- Walking inlined function calls
|
||||
- Providing a lightweight interface for "raw traces"
|
||||
- Resolving function parameter types
|
||||
- Providing traced exception objects
|
||||
- Providing an API for signal-safe stacktrace generation
|
||||
- Providing a way to retrieve stack traces from arbitrary exceptions, not just special cpptrace traced exception
|
||||
objects. This is a feature coming to C++26, but cpptrace provides a solution for C++11.
|
||||
|
||||
## What does cpptrace have over other C++ stacktrace libraries?
|
||||
|
||||
Other C++ stacktrace libraries, such as boost stacktrace and backward-cpp, fall short when it comes to portability and
|
||||
ease of use. In testing, I found neither to provide adaquate coverage of various environments. Even when they can be
|
||||
made to work in an environment they require manual configuration from the end-user, possibly requiring manual
|
||||
installation of third-party dependencies. This is a highly undesirable burden to impose on users, especially when it is
|
||||
for a software package which just provides diagnostics as opposed to core functionality. Additionally, cpptrace provides
|
||||
support for resolving inlined calls by default for DWARF symbols (boost does not do this, backward-cpp can do this but
|
||||
only for some back-ends), better support for resolving full function signatures, and nicer API, among other features.
|
||||
|
||||
# Prerequisites
|
||||
|
||||
> [!IMPORTANT]
|
||||
@ -1320,6 +1294,51 @@ A couple things I'd like to improve in the future:
|
||||
in dbghelp the library cannot accurately show const and volatile qualifiers or rvalue references (these appear as
|
||||
pointers).
|
||||
|
||||
# FAQ
|
||||
|
||||
## What about C++23 `<stacktrace>`?
|
||||
|
||||
Some day C++23's `<stacktrace>` will be ubiquitous. And maybe one day the msvc implementation will be acceptable.
|
||||
The original motivation for cpptrace was to support projects using older C++ standards and as the library has grown its
|
||||
functionality has extended beyond the standard library's implementation.
|
||||
|
||||
Cpptrace provides functionality beyond what the standard library provides and what implementations provide, such as:
|
||||
- Walking inlined function calls
|
||||
- Providing a lightweight interface for "raw traces"
|
||||
- Resolving function parameter types
|
||||
- Providing traced exception objects
|
||||
- Providing an API for signal-safe stacktrace generation
|
||||
- Providing a way to retrieve stack traces from arbitrary exceptions, not just special cpptrace traced exception
|
||||
objects. This is a feature coming to C++26, but cpptrace provides a solution for C++11.
|
||||
|
||||
## What does cpptrace have over other C++ stacktrace libraries?
|
||||
|
||||
Other C++ stacktrace libraries, such as boost stacktrace and backward-cpp, fall short when it comes to portability and
|
||||
ease of use. In testing, I found neither to provide adaquate coverage of various environments. Even when they can be
|
||||
made to work in an environment they require manual configuration from the end-user, possibly requiring manual
|
||||
installation of third-party dependencies. This is a highly undesirable burden to impose on users, especially when it is
|
||||
for a software package which just provides diagnostics as opposed to core functionality. Additionally, cpptrace provides
|
||||
support for resolving inlined calls by default for DWARF symbols (boost does not do this, backward-cpp can do this but
|
||||
only for some back-ends), better support for resolving full function signatures, and nicer API, among other features.
|
||||
|
||||
## I'm getting undefined standard library symbols like `std::__1::basic_string` on MacOS
|
||||
|
||||
If you see a linker error along the lines of the following on MacOS then it's highly likely you are mixing standard
|
||||
library ABIs.
|
||||
|
||||
```
|
||||
Undefined symbols for architecture arm64:
|
||||
"std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> >::find(char, unsigned long) const", referenced from:
|
||||
cpptrace::detail::demangle(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, bool) in libcpptrace.a(demangle_with_cxxabi.cpp.o)
|
||||
cpptrace::detail::snippet_manager::build_line_table() in libcpptrace.a(snippet.cpp.o)
|
||||
```
|
||||
|
||||
This can happen when using apple clang to compile cpptrace and gcc to compile your code, or vice versa. The reason is
|
||||
that apple clang defaults to libc++ and gcc defaults to libstdc++ and these two standard library implementations are not
|
||||
ABI-compatible. To resolve this, ensure you are compiling both cpptrace and your code with the same standard library by
|
||||
either using the same compiler for both or using `-stdlib=libc++`/`-stdlib=libstdc++` to control which standard library
|
||||
is used.
|
||||
|
||||
# Contributing
|
||||
|
||||
I'm grateful for the help I've received with this library and I welcome contributions! For information on contributing
|
||||
|
||||
Loading…
Reference in New Issue
Block a user