Merge topic 'patch-FindBacktrace'

533d5eafcb FindBacktrace: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10566

Modules/FindBacktrace.cmake

@@ -5,50 +5,103 @@
 FindBacktrace
 -------------
 
-Find provider for `backtrace(3) <https://man7.org/linux/man-pages/man3/backtrace.3.html>`__.
+Finds `backtrace(3) <https://man7.org/linux/man-pages/man3/backtrace.3.html>`_,
+a library that provides functions for application self-debugging.
+
+This module checks whether ``backtrace(3)`` is supported, either through the
+standard C library (``libc``), or a separate library.
+
+Imported Targets
+^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.30
+
+This module provides the following :ref:`Imported Targets`:
+
+``Backtrace::Backtrace``
+  An interface library encapsulating the usage requirements of Backtrace.  This
+  target is available only when Backtrace is found.
+
+Result Variables
+^^^^^^^^^^^^^^^^
 
-Checks if OS supports ``backtrace(3)`` via either ``libc`` or custom library.
 This module defines the following variables:
 
-``Backtrace_HEADER``
-  The header file needed for ``backtrace(3)``. Cached.
-  Could be forcibly set by user.
 ``Backtrace_INCLUDE_DIRS``
   The include directories needed to use ``backtrace(3)`` header.
 ``Backtrace_LIBRARIES``
   The libraries (linker flags) needed to use ``backtrace(3)``, if any.
 ``Backtrace_FOUND``
-  Is set if and only if ``backtrace(3)`` support detected.
+  Boolean indicating whether the ``backtrace(3)`` support is available.
+
+Cache Variables
+^^^^^^^^^^^^^^^
 
 The following cache variables are also available to set or use:
 
+``Backtrace_HEADER``
+  The header file needed for ``backtrace(3)``.  This variable allows dynamic
+  usage of the header in the project code.  It can also be overridden by the
+  user.
 ``Backtrace_LIBRARY``
   The external library providing backtrace, if any.
 ``Backtrace_INCLUDE_DIR``
   The directory holding the ``backtrace(3)`` header.
 
-Typical usage is to generate of header file using :command:`configure_file`
-with the contents like the following:
+Examples
+^^^^^^^^
 
-.. code-block:: c
+Finding Backtrace and linking it to a project target as of CMake 3.30:
 
- #cmakedefine01 Backtrace_FOUND
- #if Backtrace_FOUND
- # include <${Backtrace_HEADER}>
- #endif
+.. code-block:: cmake
+  :caption: CMakeLists.txt
 
-And then reference that generated header file in actual source.
+  find_package(Backtrace)
+  target_link_libraries(app PRIVATE Backtrace::Backtrace)
 
-Imported Targets
-^^^^^^^^^^^^^^^^
+The ``Backtrace_HEADER`` variable can be used, for example, in a configuration
+header file created by :command:`configure_file`:
 
-.. versionadded:: 3.30
+.. code-block:: cmake
+  :caption: CMakeLists.txt
 
-This module defines the following :prop_tgt:`IMPORTED` targets:
+  add_library(app app.c)
 
-``Backtrace::Backtrace``
-  An interface library providing usage requirements for the found components.
+  find_package(Backtrace)
+  target_link_libraries(app PRIVATE Backtrace::Backtrace)
+
+  configure_file(config.h.in config.h)
+
+.. code-block:: c
+  :caption: config.h.in
+
+  #cmakedefine01 Backtrace_FOUND
+  #if Backtrace_FOUND
+  #  include <@Backtrace_HEADER@>
+  #endif
 
+.. code-block:: c
+  :caption: app.c
+
+  #include "config.h"
+
+If the project needs to support CMake 3.29 or earlier, the imported target can
+be defined manually:
+
+.. code-block:: cmake
+  :caption: CMakeLists.txt
+
+  find_package(Backtrace)
+  if(Backtrace_FOUND AND NOT TARGET Backtrace::Backtrace)
+    add_library(Backtrace::Backtrace INTERFACE IMPORTED)
+    set_target_properties(
+      Backtrace::Backtrace
+      PROPERTIES
+        INTERFACE_LINK_LIBRARIES "${Backtrace_LIBRARIES}"
+        INTERFACE_INCLUDE_DIRECTORIES "${Backtrace_INCLUDE_DIRS}"
+    )
+  endif()
+  target_link_libraries(app PRIVATE Backtrace::Backtrace)
 #]=======================================================================]
 
 include(CMakePushCheckState)