# FindBacktrace

Finds backtrace(3), a library that provides functions for application self-debugging:

    find_package(Backtrace [...])

This module checks whether `backtrace(3)` is supported, either through the standard C library (`libc`), or a separate library.

## Imported Targets

This module provides the following Imported Targets:

`Backtrace::Backtrace`

  Added in version 3.30.

  An interface library encapsulating the usage requirements of Backtrace. This target is available only when Backtrace is found.

## Result Variables

This module defines the following variables:

`Backtrace_FOUND`

  Boolean indicating whether the `backtrace(3)` support is available.

`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.

## 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_INCLUDE_DIR`

  The directory holding the `backtrace(3)` header.

`Backtrace_LIBRARY`

  The external library providing backtrace, if any.

## Examples

Finding Backtrace and linking it to a project target as of CMake 3.30:

`CMakeLists.txt`

    find_package(Backtrace)
    target_link_libraries(app PRIVATE Backtrace::Backtrace)

The `Backtrace_HEADER` variable can be used, for example, in a configuration header file created by `configure_file()`:

`CMakeLists.txt`

    add_library(app app.c)

    find_package(Backtrace)
    target_link_libraries(app PRIVATE Backtrace::Backtrace)

    configure_file(config.h.in config.h)

`config.h.in`

    #cmakedefine01 Backtrace_FOUND
    #if Backtrace_FOUND
    #  include <@Backtrace_HEADER@>
    #endif

`app.c`

    #include "config.h"

If the project needs to support CMake 3.29 or earlier, the imported target can be defined manually:

`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)