Add usage info to the README and fix a cmake error
This commit is contained in:
Jeremy
parent
2d86770348
commit
f28c2cac3a
@ -326,8 +326,8 @@ if(NOT CMAKE_SKIP_INSTALL_RULES)
|
||||
|
||||
install(
|
||||
FILES
|
||||
include/cpptrace.hpp
|
||||
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cpptrace/cpptrace
|
||||
include/cpptrace/cpptrace.hpp
|
||||
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cpptrace
|
||||
)
|
||||
|
||||
export(
|
||||
|
||||
72
README.md
72
README.md
@ -32,11 +32,45 @@ Some day C++23's `<stacktrace>` will be ubiquitous. And maybe one day the msvc i
|
||||
|
||||
### CMake FetchContent
|
||||
|
||||
TODO
|
||||
```cmake
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(
|
||||
cpptrace
|
||||
GIT_REPOSITORY https://github.com/jeremy-rifkin/cpptrace.git
|
||||
GIT_TAG <HASH or TAG>
|
||||
)
|
||||
FetchContent_MakeAvailable(cpptrace)
|
||||
target_link_libraries(your_target PRIVATE cpptrace)
|
||||
```
|
||||
|
||||
### System-wide installation
|
||||
|
||||
TODO
|
||||
```sh
|
||||
git clone https://github.com/jeremy-rifkin/cpptrace.git
|
||||
# optional: git checkout <HASH or TAG>
|
||||
mkdir cpptrace/build
|
||||
cd cpptrace/build
|
||||
cmake .. -DCMAKE_BUILD_TYPE=debug -DBUILD_SHARED_LIBS=On
|
||||
make
|
||||
sudo make install
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Or on windows</summary>
|
||||
|
||||
```ps1
|
||||
git clone https://github.com/jeremy-rifkin/cpptrace.git
|
||||
# optional: git checkout <HASH or TAG>
|
||||
mkdir cpptrace/build
|
||||
cd cpptrace/build
|
||||
cmake .. -DCMAKE_BUILD_TYPE=debug -DBUILD_SHARED_LIBS=On
|
||||
msbuild cpptrace.sln
|
||||
msbuild INSTALL.vcxproj
|
||||
```
|
||||
|
||||
Note: You'll need to run as an administrator in a developer powershell, or use vcvarsall.bat distributed with visual
|
||||
studio to get the correct environment variables set.
|
||||
</details>
|
||||
|
||||
### Conan
|
||||
|
||||
@ -78,34 +112,36 @@ also manually set which back-end you want used.
|
||||
|
||||
**Unwinding**
|
||||
|
||||
| Library | CMake config | Windows | Linux | macOS | Info |
|
||||
| ---------- | ------------------------------- | ------- | ----- | ----- | ------------------------------------------------------------------ |
|
||||
| execinfo.h | `CPPTRACE_UNWIND_WITH_EXECINFO` | ❌ | ✔️ | ✔️ | Frames are captured with `execinfo.h`'s `backtrace`, part of libc. |
|
||||
| winapi | `CPPTRACE_UNWIND_WITH_WINAPI` | ✔️ | ❌ | ❌ | Frames are captured with `CaptureStackBackTrace`. |
|
||||
| N/A | `CPPTRACE_UNWIND_WITH_NOTHING` | ✔️ | ✔️ | ✔️ | Unwinding is not done, stack traces will be empty. |
|
||||
| Library | CMake config | Platforms | Info |
|
||||
| ---------- | ------------------------------- | -------------- | ------------------------------------------------------------------ |
|
||||
| execinfo.h | `CPPTRACE_UNWIND_WITH_EXECINFO` | linux, macos | Frames are captured with `execinfo.h`'s `backtrace`, part of libc. |
|
||||
| winapi | `CPPTRACE_UNWIND_WITH_WINAPI` | windows, mingw | Frames are captured with `CaptureStackBackTrace`. |
|
||||
| N/A | `CPPTRACE_UNWIND_WITH_NOTHING` | all | Unwinding is not done, stack traces will be empty. |
|
||||
|
||||
These back-ends require a fixed buffer has to be created to read addresses into while unwinding. By default the buffer
|
||||
can hold addresses for 100 frames (beyond the `skip` frames). This is configurable with `CPPTRACE_HARD_MAX_FRAMES`.
|
||||
|
||||
**Symbol resolution**
|
||||
|
||||
| Library | CMake config | Windows | Linux | macOS | Info |
|
||||
| ------------ | ---------------------------------------- | ------- | ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| libbacktrace | `CPPTRACE_GET_SYMBOLS_WITH_LIBBACKTRACE` | ❌ | ✔️ | ❌ | Libbacktrace is already installed on most systems, or available through the compiler directly. If it is installed but backtrace.h is not already in the include path (this can happen when using clang when backtrace lives in gcc's include folder), `CPPTRACE_BACKTRACE_PATH` can be used to specify where the library should be looked for. |
|
||||
| libdl | `CPPTRACE_GET_SYMBOLS_WITH_LIBDL` | ❌ | ✔️ | ✔️ | Libdl uses dynamic export information. Compiling with `-rdynamic` is needed for symbol information to be retrievable. |
|
||||
| addr2line | `CPPTRACE_GET_SYMBOLS_WITH_ADDR2LINE` | ❌ | ✔️ | ❌ (TODO) | Symbols are resolved by invoking `addr2line` via `fork()`. |
|
||||
| dbghelp | `CPPTRACE_GET_SYMBOLS_WITH_DBGHELP` | ✔️ | ❌ | ❌ | Dbghelp.h allows access to symbols via debug info. |
|
||||
| N/A | `CPPTRACE_GET_SYMBOLS_WITH_NOTHING` | ✔️ | ✔️ | ✔️ | No attempt is made to resolve symbols. |
|
||||
| Library | CMake config | Platforms | Info |
|
||||
| ------------ | ---------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| libbacktrace | `CPPTRACE_GET_SYMBOLS_WITH_LIBBACKTRACE` | linux, macos*, mingw* | Libbacktrace is already installed on most systems, or available through the compiler directly. If it is installed but backtrace.h is not already in the include path (this can happen when using clang when backtrace lives in gcc's include folder), `CPPTRACE_BACKTRACE_PATH` can be used to specify where the library should be looked for. |
|
||||
| libdl | `CPPTRACE_GET_SYMBOLS_WITH_LIBDL` | linux, macos | Libdl uses dynamic export information. Compiling with `-rdynamic` is needed for symbol information to be retrievable. |
|
||||
| addr2line | `CPPTRACE_GET_SYMBOLS_WITH_ADDR2LINE` | linux, mingw(TODO), macos(TODO) | Symbols are resolved by invoking `addr2line` via `fork()`. |
|
||||
| dbghelp | `CPPTRACE_GET_SYMBOLS_WITH_DBGHELP` | windows | Dbghelp.h allows access to symbols via debug info. |
|
||||
| N/A | `CPPTRACE_GET_SYMBOLS_WITH_NOTHING` | all | No attempt is made to resolve symbols. |
|
||||
|
||||
*: Requires installation
|
||||
|
||||
**Demangling**
|
||||
|
||||
Lastly, depending on other back-ends used a demangler back-end may be needed. A demangler back-end is not needed when
|
||||
doing full traces with libbacktrace, getting symbols with addr2line, or getting symbols with dbghelp.
|
||||
|
||||
| Library | CMake config | Windows | Linux | Info |
|
||||
| -------- | -------------------------------- | ------- | ----- | ---------------------------------------------------------------------------------- |
|
||||
| cxxabi.h | `CPPTRACE_DEMANGLE_WITH_CXXABI` | | | Should be available everywhere other than [msvc](https://godbolt.org/z/93ca9rcdz). |
|
||||
| N/A | `CPPTRACE_DEMANGLE_WITH_NOTHING` | | | Don't attempt to do anything beyond what the symbol resolution back-end does. |
|
||||
| Library | CMake config | Platforms | Info |
|
||||
| -------- | -------------------------------- | ------------------- | ---------------------------------------------------------------------------------- |
|
||||
| cxxabi.h | `CPPTRACE_DEMANGLE_WITH_CXXABI` | Linux, macos, mingw | Should be available everywhere other than [msvc](https://godbolt.org/z/93ca9rcdz). |
|
||||
| N/A | `CPPTRACE_DEMANGLE_WITH_NOTHING` | all | Don't attempt to do anything beyond what the symbol resolution back-end does. |
|
||||
|
||||
**Full tracing**
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user