luo980/cpptrace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add usage info to the README and fix a cmake error

Browse Source
This commit is contained in:
Jeremy 2023-07-15 11:01:37 -04:00
parent 2d86770348
commit f28c2cac3a
No known key found for this signature in database
GPG Key ID: 19AA8270105E8EB4
2 changed files with 56 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CMakeLists.txt
View File

@ -326,8 +326,8 @@ if(NOT CMAKE_SKIP_INSTALL_RULES)
install( install(
FILES FILES
include/cpptrace.hpp include/cpptrace/cpptrace.hpp
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cpptrace/cpptrace DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cpptrace
) )
export( export(

72
README.md
View File

@ -32,11 +32,45 @@ Some day C++23's `<stacktrace>` will be ubiquitous. And maybe one day the msvc i
### CMake FetchContent ### 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 ### 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 ### Conan
@ -78,34 +112,36 @@ also manually set which back-end you want used.
**Unwinding** **Unwinding**
| Library | CMake config | Windows | Linux | macOS | Info | | Library | CMake config | Platforms | Info |
| ---------- | ------------------------------- | ------- | ----- | ----- | ------------------------------------------------------------------ | | ---------- | ------------------------------- | -------------- | ------------------------------------------------------------------ |
| execinfo.h | `CPPTRACE_UNWIND_WITH_EXECINFO` | ❌ | ✔️ | ✔️ | Frames are captured with `execinfo.h`'s `backtrace`, part of libc. | | execinfo.h | `CPPTRACE_UNWIND_WITH_EXECINFO` | linux, macos | Frames are captured with `execinfo.h`'s `backtrace`, part of libc. |
| winapi | `CPPTRACE_UNWIND_WITH_WINAPI` | ✔️ | ❌ | ❌ | Frames are captured with `CaptureStackBackTrace`. | | winapi | `CPPTRACE_UNWIND_WITH_WINAPI` | windows, mingw | Frames are captured with `CaptureStackBackTrace`. |
| N/A | `CPPTRACE_UNWIND_WITH_NOTHING` | ✔️ | ✔️ | ✔️ | Unwinding is not done, stack traces will be empty. | | 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 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`. can hold addresses for 100 frames (beyond the `skip` frames). This is configurable with `CPPTRACE_HARD_MAX_FRAMES`.
**Symbol resolution** **Symbol resolution**
| Library | CMake config | Windows | Linux | macOS | Info | | Library | CMake config | Platforms | 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. | | 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` | ❌ | ✔️ | ✔️ | Libdl uses dynamic export information. Compiling with `-rdynamic` is needed for symbol information to be retrievable. | | 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` | ❌ | ✔️ | ❌ (TODO) | Symbols are resolved by invoking `addr2line` via `fork()`. | | 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` | ✔️ | ❌ | ❌ | Dbghelp.h allows access to symbols via debug info. | | dbghelp | `CPPTRACE_GET_SYMBOLS_WITH_DBGHELP` | windows | Dbghelp.h allows access to symbols via debug info. |
| N/A | `CPPTRACE_GET_SYMBOLS_WITH_NOTHING` | ✔️ | ✔️ | ✔️ | No attempt is made to resolve symbols. | | N/A | `CPPTRACE_GET_SYMBOLS_WITH_NOTHING` | all | No attempt is made to resolve symbols. |
*: Requires installation
**Demangling** **Demangling**
Lastly, depending on other back-ends used a demangler back-end may be needed. A demangler back-end is not needed when 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. doing full traces with libbacktrace, getting symbols with addr2line, or getting symbols with dbghelp.
| Library | CMake config | Windows | Linux | Info | | Library | CMake config | Platforms | Info |
| -------- | -------------------------------- | ------- | ----- | ---------------------------------------------------------------------------------- | | -------- | -------------------------------- | ------------------- | ---------------------------------------------------------------------------------- |
| cxxabi.h | `CPPTRACE_DEMANGLE_WITH_CXXABI` | | | Should be available everywhere other than [msvc](https://godbolt.org/z/93ca9rcdz). | | 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` | | | Don't attempt to do anything beyond what the symbol resolution back-end does. | | N/A | `CPPTRACE_DEMANGLE_WITH_NOTHING` | all | Don't attempt to do anything beyond what the symbol resolution back-end does. |
**Full tracing** **Full tracing**