diff --git a/README.md b/README.md index dfddba7..1184638 100644 --- a/README.md +++ b/README.md @@ -45,10 +45,26 @@ Note for [folly](https://github.com/facebook/folly) library users: must define ` ### Integration with CMake -If you are using CMake and want to use its configuration abilities to save -you the trouble, you can easily integrate Backward, depending on how you obtained +If you are using CMake and want to use its configuration abilities to save you +the trouble, you can easily integrate Backward, depending on how you obtained the library. +Notice that all approaches are equivalent in the way Backward is added to a +CMake target, the difference is in how CMake is pointed to the Backward +sources. Backward defines three targets: + +- `Backward::Interface` is an interface target that brings compiler definition + flags, include directory, and external libraries. This is all you need to use + the `backward.hpp` header library. +- `Backward::Object` brings `Backward::Interface` and `backward.cpp` as an + `OBJECT` CMake library. This target cannot be exported, so it is not + available when Backward is used via `find_package`. +- `Backward::Backward` brings `Backward::Interface` and `backward.cpp` as + either `STATIC` or `SHARED` library (depending on the `BACKWARD_SHARED` + option). This target is exported and always available, however note that the + linker will not include unused objects from a static library, unless the + `-Wl,--whole-archive` option (or similar) is used. + #### With `FetchContent()`: If you are using a recent version of CMake, you can integrate `backward` via `FetchContent` like below: @@ -58,32 +74,30 @@ include(FetchContent) # Also requires one of: libbfd (gnu binutils), libdwarf, libdw (elfutils) FetchContent_Declare(backward - GIT_REPOSITORY https://github.com/bombela/backward-cpp - GIT_TAG v1.6) + GIT_REPOSITORY https://github.com/bombela/backward-cpp + GIT_TAG master # or a version tag, such as v1.6 + SYSTEM # optional, the Backward include directory will be treated as system directory +) FetchContent_MakeAvailable(backward) -file(GLOB_RECURSE SOURCES CONFIGURE_DEPENDS src/*.cpp) -add_executable(example ${SOURCES} ${BACKWARD_ENABLE}) # Notice the "BACKWARD_ENABLE" here -add_backward(example) +# Add Backward to your target (either Backward::Interface, Backward::Object, or Backward::Backward) +target_link_libraries(mytarget PUBLIC Backward::Interface) ``` #### As a subdirectory: In this case you have a subdirectory containing the whole repository of Backward -(eg.: using git-submodules), in this case you can do: +(e.g. using [git-submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)), +in this case you can do: -``` +```cmake add_subdirectory(/path/to/backward-cpp) -# This will add backward.cpp to your target -add_executable(mytarget mysource.cpp ${BACKWARD_ENABLE}) - -# This will add libraries, definitions and include directories needed by backward -# by setting each property on the target. -add_backward(mytarget) +# Add Backward to your target (either Backward::Interface, Backward::Object, or Backward::Backward) +target_link_libraries(mytarget PUBLIC Backward::Interface) ``` -#### Modifying CMAKE_MODULE_PATH +#### Modifying `CMAKE_MODULE_PATH`: In this case you can have Backward installed as a subdirectory: @@ -91,14 +105,10 @@ In this case you can have Backward installed as a subdirectory: list(APPEND CMAKE_MODULE_PATH /path/to/backward-cpp) find_package(Backward) -# This will add libraries, definitions and include directories needed by backward -# through an IMPORTED target. -target_link_libraries(mytarget PUBLIC Backward::Backward) +# Add Backward to your target (either Backward::Interface or Backward::Backward) +target_link_libraries(mytarget PUBLIC Backward::Interface) ``` -Notice that this is equivalent to using the the approach that uses `add_subdirectory()`, -however it uses cmake's [imported target](https://cmake.org/Wiki/CMake/Tutorials/Exporting_and_Importing_Targets) mechanism. - #### Installation through a regular package manager In this case you have obtained Backward through a package manager. @@ -109,10 +119,10 @@ Packages currently available: ``` find_package(Backward) -# This will add libraries, definitions and include directories needed by backward -# through an IMPORTED target. -target_link_libraries(mytarget PUBLIC Backward::Backward) +# Add Backward to your target (either Backward::Interface or Backward::Backward) +target_link_libraries(mytarget PUBLIC Backward::Interface) ``` + ### Libraries to unwind the stack On Linux and macOS, backtrace can back-trace or "walk" the stack using the