Add static option and overhaul README a bit

2023-09-12 23:59:10 -04:00 · 2023-09-12 23:59:10 -04:00 · e068a3dadd
commit e068a3dadd
parent 906687e2db
2 changed files with 106 additions and 41 deletions
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -22,6 +22,8 @@ if(CMAKE_GENERATOR STREQUAL "Ninja")
  endif()
 endif()

+option(CPPTRACE_STATIC "" OFF)
+
 option(CPPTRACE_FULL_TRACE_WITH_LIBBACKTRACE "" OFF)
 option(CPPTRACE_FULL_TRACE_WITH_STACKTRACE "" OFF)

@ -237,7 +239,11 @@ set(
  src/unwind/unwind_with_winapi.cpp
 )

-add_library(cpptrace SHARED ${sources} include/cpptrace/cpptrace.hpp)
+if(CPPTRACE_STATIC)
+  add_library(cpptrace STATIC ${sources} include/cpptrace/cpptrace.hpp)
+else()
+  add_library(cpptrace SHARED ${sources} include/cpptrace/cpptrace.hpp)
+endif()

 target_include_directories(
  cpptrace
@ -402,14 +408,25 @@ endif()
 if(NOT CMAKE_SKIP_INSTALL_RULES)
  include(CMakePackageConfigHelpers)

-  install(
-    TARGETS cpptrace
-    EXPORT cpptrace_targets
-    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
-    INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
-    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
-    RUNTIME DESTINATION ${CMAKE_INSTALL_LIBDIR}
-  )
+  if(CPPTRACE_STATIC)
+    install(
+      TARGETS cpptrace dwarf
+      EXPORT cpptrace_targets
+      LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+      ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      RUNTIME DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    )
+  else()
+    install(
+      TARGETS cpptrace
+      EXPORT cpptrace_targets
+      LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+      ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      RUNTIME DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    )
+  endif()

  install(
    FILES
--- a/README.md
+++ b/README.md
@ -1,4 +1,4 @@
-# Cpptrace
+# Cpptrace <!-- omit in toc -->

 [![build](https://github.com/jeremy-rifkin/cpptrace/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/jeremy-rifkin/cpptrace/actions/workflows/build.yml)
 [![test](https://github.com/jeremy-rifkin/cpptrace/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/jeremy-rifkin/cpptrace/actions/workflows/test.yml)
@ -18,21 +18,58 @@ This library is in beta, if you run into any problems please open an [issue][iss

 [issue]: https://github.com/jeremy-rifkin/cpptrace/issues

-## Table of Contents
+## Table of Contents <!-- omit in toc -->

- [Cpptrace](#cpptrace)
-  - [Table of Contents](#table-of-contents)
-  - [Quick Setup](#quick-setup)
-  - [Other Installation Mechanisms](#other-installation-mechanisms)
+- [30-Second Overview](#30-second-overview)
+  - [CMake FetchContent Usage](#cmake-fetchcontent-usage)
+- [In-Depth Documentation](#in-depth-documentation)
+  - [Usage](#usage)
+    - [CMake FetchContent](#cmake-fetchcontent)
    - [System-Wide Installation](#system-wide-installation)
+    - [Local User Installation](#local-user-installation)
    - [Package Managers](#package-managers)
+    - [Platform Logistics](#platform-logistics)
+    - [Static Linking](#static-linking)
  - [API](#api)
  - [Back-ends](#back-ends)
    - [Summary of Library Configurations](#summary-of-library-configurations)
  - [Testing Methodology](#testing-methodology)
-  - [License](#license)
+- [License](#license)

-## Quick Setup
+# 30-Second Overview
+
+```cpp
+#include <cpptrace/cpptrace.hpp>
+
+void trace() {
+    cpptrace::print_trace();
+}
+
+// ...
+```
+
+![Screenshot](res/screenshot.png)
+
+## CMake FetchContent Usage
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(
+  cpptrace
+  GIT_REPOSITORY https://github.com/jeremy-rifkin/cpptrace.git
+  GIT_TAG        v0.1.1 # <HASH or TAG>
+)
+FetchContent_MakeAvailable(cpptrace)
+target_link_libraries(your_target cpptrace)
+```
+
+On windows and macos some extra work is required, see [below](#platform-logistics).
+
+# In-Depth Documentation
+
+## Usage
+
+### CMake FetchContent

 With CMake FetchContent:

@ -45,34 +82,14 @@ FetchContent_Declare(
 )
 FetchContent_MakeAvailable(cpptrace)
 target_link_libraries(your_target cpptrace)
-
-if(WIN32) # Copy the .dll on windows
-  add_custom_command(
-    TARGET your_target POST_BUILD
-    COMMAND ${CMAKE_COMMAND} -E copy_if_different
-    $<TARGET_FILE:cpptrace>
-    $<TARGET_FILE_DIR:your_target>
-  )
-endif()
-
-if(APPLE) # Create a .dSYM file on apple. Currently required, but hopefully not for long
-  add_custom_command(
-    TARGET your_target
-    POST_BUILD
-    COMMAND dsymutil $<TARGET_FILE:your_target>
-  )
-endif()
 ```

-It's as easy as that. Cpptrace will automatically configure itself for your system.
+It's as easy as that. Cpptrace will automatically configure itself for your system. Note: On windows and macos some
+extra work is required, see [below](#platform-logistics).

 Be sure to configure with `-DCMAKE_BUILD_TYPE=Debug` or `-DDCMAKE_BUILD_TYPE=RelWithDebInfo` for symbols and line
 information.

-![Screenshot](res/screenshot.png)
-
-## Other Installation Mechanisms
-
 ### System-Wide Installation

 ```sh
@ -154,6 +171,36 @@ g++ main.cpp -o main -g -Wall -I$HOME/wherever/include -L$HOME/wherever/lib -lcp

 Coming soon

+### Platform Logistics
+
+Windows and macos require a little extra work to get everything in the right place
+
+```cmake
+# Copy the cpptrace.dll on windows to the same directory as the executable for your_target.
+# Not required if static linking.
+if(WIN32)
+  add_custom_command(
+    TARGET your_target POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+    $<TARGET_FILE:cpptrace>
+    $<TARGET_FILE_DIR:your_target>
+  )
+endif()
+
+# Create a .dSYM file on macos. Currently required, but hopefully not for long
+if(APPLE)
+  add_custom_command(
+    TARGET your_target
+    POST_BUILD
+    COMMAND dsymutil $<TARGET_FILE:your_target>
+  )
+endif()
+```
+
+### Static Linking
+
+To static link the library set `CPPTRACE_STATIC=On`.
+
 ## API

 `cpptrace::print_trace()` can be used to print a stacktrace at the current call site, `cpptrace::generate_trace()` can
@ -260,7 +307,8 @@ Back-ends:
 - `CPPTRACE_DEMANGLE_WITH_NOTHING=On/Off`

 Back-end configuration:
- `CPPTRACE_BACKTRACE_PATH=<string>`: Path to libbacktrace backtrace.h, needed when compiling with clang
+- `CPPTRACE_STATIC=On/Off`: Create the cpptrace library as a static library.
+- `CPPTRACE_BACKTRACE_PATH=<string>`: Path to libbacktrace backtrace.h, needed when compiling with clang/
 - `CPPTRACE_HARD_MAX_FRAMES=<number>`: Some back-ends write to a fixed-size buffer. This is the size of that buffer.
  Default is `100`.
 - `CPPTRACE_ADDR2LINE_PATH=<string>`: Specify the absolute path to the addr2line binary for cpptrace to invoke. By
@ -288,7 +336,7 @@ unwinding back-end, and the python script will check for an exact or near-match

 [1]: https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs

-## License
+# License

 This library is under the MIT license.