From bb44252f1e5d2b230dabdad1f44b5a889609a6cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Klinkovsk=C3=BD?= <j.l.k@gmx.com>
Date: Fri, 1 Sep 2023 22:19:16 +0200
Subject: [PATCH] Modernize CMake instructions in the README

---
 README.md | 60 ++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 35 insertions(+), 25 deletions(-)

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