Skip to content

Commit f28c2ca

Browse files
jeremy-rifkinjeremy-rifkin
committed
Add usage info to the README and fix a cmake error
1 parent 2d86770 commit f28c2ca

File tree

2 files changed

+56
-20
lines changed

2 files changed

+56
-20
lines changed

‎CMakeLists.txt

+2-2
Original file line numberDiff line numberDiff line change
@@ -326,8 +326,8 @@ if(NOT CMAKE_SKIP_INSTALL_RULES)
326326

327327
install(
328328
FILES
329-
include/cpptrace.hpp
330-
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cpptrace/cpptrace
329+
include/cpptrace/cpptrace.hpp
330+
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/cpptrace
331331
)
332332

333333
export(

‎README.md

+54-18
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,45 @@ Some day C++23's `<stacktrace>` will be ubiquitous. And maybe one day the msvc i
3232

3333
### CMake FetchContent
3434

35-
TODO
35+
```cmake
36+
include(FetchContent)
37+
FetchContent_Declare(
38+
cpptrace
39+
GIT_REPOSITORY https://github.com/jeremy-rifkin/cpptrace.git
40+
GIT_TAG <HASH or TAG>
41+
)
42+
FetchContent_MakeAvailable(cpptrace)
43+
target_link_libraries(your_target PRIVATE cpptrace)
44+
```
3645

3746
### System-wide installation
3847

39-
TODO
48+
```sh
49+
git clone https://github.com/jeremy-rifkin/cpptrace.git
50+
# optional: git checkout <HASH or TAG>
51+
mkdir cpptrace/build
52+
cd cpptrace/build
53+
cmake .. -DCMAKE_BUILD_TYPE=debug -DBUILD_SHARED_LIBS=On
54+
make
55+
sudo make install
56+
```
57+
58+
<details>
59+
<summary>Or on windows</summary>
60+
61+
```ps1
62+
git clone https://github.com/jeremy-rifkin/cpptrace.git
63+
# optional: git checkout <HASH or TAG>
64+
mkdir cpptrace/build
65+
cd cpptrace/build
66+
cmake .. -DCMAKE_BUILD_TYPE=debug -DBUILD_SHARED_LIBS=On
67+
msbuild cpptrace.sln
68+
msbuild INSTALL.vcxproj
69+
```
70+
71+
Note: You'll need to run as an administrator in a developer powershell, or use vcvarsall.bat distributed with visual
72+
studio to get the correct environment variables set.
73+
</details>
4074

4175
### Conan
4276

@@ -78,34 +112,36 @@ also manually set which back-end you want used.
78112
79113
**Unwinding**
80114
81-
| Library | CMake config | Windows | Linux | macOS | Info |
82-
| ---------- | ------------------------------- | ------- | ----- | ----- | ------------------------------------------------------------------ |
83-
| execinfo.h | `CPPTRACE_UNWIND_WITH_EXECINFO` | ❌ | ✔️ | ✔️ | Frames are captured with `execinfo.h`'s `backtrace`, part of libc. |
84-
| winapi | `CPPTRACE_UNWIND_WITH_WINAPI` | ✔️ | ❌ | ❌ | Frames are captured with `CaptureStackBackTrace`. |
85-
| N/A | `CPPTRACE_UNWIND_WITH_NOTHING` | ✔️ | ✔️ | ✔️ | Unwinding is not done, stack traces will be empty. |
115+
| Library | CMake config | Platforms | Info |
116+
| ---------- | ------------------------------- | -------------- | ------------------------------------------------------------------ |
117+
| execinfo.h | `CPPTRACE_UNWIND_WITH_EXECINFO` | linux, macos | Frames are captured with `execinfo.h`'s `backtrace`, part of libc. |
118+
| winapi | `CPPTRACE_UNWIND_WITH_WINAPI` | windows, mingw | Frames are captured with `CaptureStackBackTrace`. |
119+
| N/A | `CPPTRACE_UNWIND_WITH_NOTHING` | all | Unwinding is not done, stack traces will be empty. |
86120
87121
These back-ends require a fixed buffer has to be created to read addresses into while unwinding. By default the buffer
88122
can hold addresses for 100 frames (beyond the `skip` frames). This is configurable with `CPPTRACE_HARD_MAX_FRAMES`.
89123
90124
**Symbol resolution**
91125
92-
| Library | CMake config | Windows | Linux | macOS | Info |
93-
| ------------ | ---------------------------------------- | ------- | ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94-
| 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. |
95-
| libdl | `CPPTRACE_GET_SYMBOLS_WITH_LIBDL` | ❌ | ✔️ | ✔️ | Libdl uses dynamic export information. Compiling with `-rdynamic` is needed for symbol information to be retrievable. |
96-
| addr2line | `CPPTRACE_GET_SYMBOLS_WITH_ADDR2LINE` | ❌ | ✔️ | ❌ (TODO) | Symbols are resolved by invoking `addr2line` via `fork()`. |
97-
| dbghelp | `CPPTRACE_GET_SYMBOLS_WITH_DBGHELP` | ✔️ | ❌ | ❌ | Dbghelp.h allows access to symbols via debug info. |
98-
| N/A | `CPPTRACE_GET_SYMBOLS_WITH_NOTHING` | ✔️ | ✔️ | ✔️ | No attempt is made to resolve symbols. |
126+
| Library | CMake config | Platforms | Info |
127+
| ------------ | ---------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
128+
| 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. |
129+
| libdl | `CPPTRACE_GET_SYMBOLS_WITH_LIBDL` | linux, macos | Libdl uses dynamic export information. Compiling with `-rdynamic` is needed for symbol information to be retrievable. |
130+
| addr2line | `CPPTRACE_GET_SYMBOLS_WITH_ADDR2LINE` | linux, mingw(TODO), macos(TODO) | Symbols are resolved by invoking `addr2line` via `fork()`. |
131+
| dbghelp | `CPPTRACE_GET_SYMBOLS_WITH_DBGHELP` | windows | Dbghelp.h allows access to symbols via debug info. |
132+
| N/A | `CPPTRACE_GET_SYMBOLS_WITH_NOTHING` | all | No attempt is made to resolve symbols. |
133+
134+
*: Requires installation
99135
100136
**Demangling**
101137
102138
Lastly, depending on other back-ends used a demangler back-end may be needed. A demangler back-end is not needed when
103139
doing full traces with libbacktrace, getting symbols with addr2line, or getting symbols with dbghelp.
104140
105-
| Library | CMake config | Windows | Linux | Info |
106-
| -------- | -------------------------------- | ------- | ----- | ---------------------------------------------------------------------------------- |
107-
| cxxabi.h | `CPPTRACE_DEMANGLE_WITH_CXXABI` | | | Should be available everywhere other than [msvc](https://godbolt.org/z/93ca9rcdz). |
108-
| N/A | `CPPTRACE_DEMANGLE_WITH_NOTHING` | | | Don't attempt to do anything beyond what the symbol resolution back-end does. |
141+
| Library | CMake config | Platforms | Info |
142+
| -------- | -------------------------------- | ------------------- | ---------------------------------------------------------------------------------- |
143+
| cxxabi.h | `CPPTRACE_DEMANGLE_WITH_CXXABI` | Linux, macos, mingw | Should be available everywhere other than [msvc](https://godbolt.org/z/93ca9rcdz). |
144+
| N/A | `CPPTRACE_DEMANGLE_WITH_NOTHING` | all | Don't attempt to do anything beyond what the symbol resolution back-end does. |
109145
110146
**Full tracing**
111147

0 commit comments

Comments
 (0)