SelectLibraryConfigurations — CMake 4.1.4 Documentation

# SelectLibraryConfigurations

This module is intended for use in Find Modules and provides a command to automatically set library variables when package is available with multiple Build Configurations.

Load it in a CMake find module with:

    include(SelectLibraryConfigurations)

Supported build configurations are `Release` and `Debug` as these are the most common ones in such packages.

Note

This module has been available since early versions of CMake, when the `<PackageName>_LIBRARIES` result variable was used for linking found packages. When writing standard find modules, Imported Targets should be preferred. In addition to or as an alternative to this module, imported targets provide finer control over linking through the `IMPORTED_CONFIGURATIONS` property.

## Commands

This module provides the following command:

select_library_configurations

  Sets and adjusts library variables based on debug and release build configurations:

      select_library_configurations(<basename>)

  This command is a helper for setting the `<basename>_LIBRARY` and `<basename>_LIBRARIES` result variables when a library might be provided with multiple build configurations.

  The argument is:

  `<basename>`

    The base name of the library, used as a prefix for variable names. This is the name of the package as used in the `Find<PackageName>.cmake` module filename, or the component name, when find module provides them.

  Prior to calling this command the following cache variables should be set in the find module (for example, by the `find_library()` command):

  `<basename>_LIBRARY_RELEASE`

    A cache variable storing the full path to the `Release` build of the library. If not set or found, this command will set its value to `<basename>_LIBRARY_RELEASE-NOTFOUND`.

  `<basename>_LIBRARY_DEBUG`

    A cache variable storing the full path to the `Debug` build of the library. If not set or found, this command will set its value to `<basename>_LIBRARY_DEBUG-NOTFOUND`.

  This command then sets the following local result variables:

  `<basename>_LIBRARY`

    A result variable that is set to the value of `<basename>_LIBRARY_RELEASE` variable if found, otherwise it is set to the value of `<basename>_LIBRARY_DEBUG` variable if found. If both are found, the release library value takes precedence. If both are not found, it is set to value `<basename>_LIBRARY-NOTFOUND`.

    If the `CMake Generator` in use supports build configurations, then this variable will be a list of found libraries each prepended with the `optimized` or `debug` keywords specifying which library should be linked for the given configuration. These keywords are used by the `target_link_libraries()` command. If a build configuration has not been set or the generator in use does not support build configurations, then this variable value will not contain these keywords.

  `<basename>_LIBRARIES`

    A result variable that is set to the same value as the `<basename>_LIBRARY` variable.

  Note

  The `select_library_configurations()` command should be called before handling standard find module arguments with `find_package_handle_standard_args()` to ensure that the `<PackageName>_FOUND` result variable is correctly set based on `<basename>_LIBRARY` or other related variables.

## Examples

Setting library variables based on the build configuration inside a find module file:

`FindFoo.cmake`

    # Find release and debug build of the library
    find_library(Foo_LIBRARY_RELEASE ...)
    find_library(Foo_LIBRARY_DEBUG ...)

    # Set Foo_LIBRARY and Foo_LIBRARIES result variables
    include(SelectLibraryConfigurations)
    select_library_configurations(Foo)

    # Set Foo_FOUND variable and print result message.
    include(FindPackageHandleStandardArgs)
    find_package_handle_standard_args(
      Foo
      REQUIRED_VARS Foo_LIBRARY ...
    )

When find module provides components with multiple build configurations:

`FindFoo.cmake`

    include(SelectLibraryConfigurations)
    foreach(component IN LISTS Foo_FIND_COMPONENTS)
      # ...
      select_library_configurations(Foo_${component})
      # ...
    endforeach()

A project can then use this find module as follows:

`CMakeLists.txt`

    find_package(Foo)
    target_link_libraries(project_target PRIVATE ${Foo_LIBRARIES})
    # ...