SelectLibraryConfigurations

此模块提供了一个命令，用于在软件包具有多种构建配置时自动设置库变量。它旨在供实现 find_package(<PackageName>) 调用的查找模块 (Find Modules) 使用。

在 CMake 查找模块中加载此模块，使用

FindFoo.cmake

include(SelectLibraryConfigurations)

支持的构建配置为 Release 和 Debug，因为它们是此类软件包中最常见的配置。

注意

该模块自 CMake 早期版本起就已存在，当时使用 <PackageName>_LIBRARIES 结果变量来链接找到的软件包。编写标准查找模块时，应优先使用导入的目标 (Imported Targets)。除了该模块或作为其替代方案，导入的目标通过 IMPORTED_CONFIGURATIONS 属性提供了对链接的更精细控制。

命令

此模块提供以下命令

select_library_configurations

根据调试 (debug) 和发布 (release) 构建配置设置并调整库变量

select_library_configurations(<basename>)

当库可能提供多种构建配置时，此命令是设置 <basename>_LIBRARY 和 <basename>_LIBRARIES 结果变量的辅助工具。

参数为

<basename>

库的基本名称，用作变量名的前缀。这是 Find<PackageName>.cmake 模块文件名中使用的包名称，或者是查找模块提供组件时的组件名称。

在调用此命令之前，应在查找模块中设置以下缓存变量（例如，通过 find_library() 命令）

<basename>_LIBRARY_RELEASE

存储 Release 版库完整路径的缓存变量。如果未设置或未找到，此命令会将其值设置为 <basename>_LIBRARY_RELEASE-NOTFOUND。

<basename>_LIBRARY_DEBUG

存储 Debug 版库完整路径的缓存变量。如果未设置或未找到，此命令会将其值设置为 <basename>_LIBRARY_DEBUG-NOTFOUND。

此命令随后设置以下本地结果变量

<basename>_LIBRARY

一个结果变量，如果找到则设置为 <basename>_LIBRARY_RELEASE 变量的值，否则如果找到则设置为 <basename>_LIBRARY_DEBUG 变量的值。如果两者都找到，则发布版库的值优先。如果两者都未找到，则将其设置为 <basename>_LIBRARY-NOTFOUND。

如果正在使用的 CMake 生成器 支持构建配置，则此变量将是一个找到的库列表，每个库前都会加上 optimized 或 debug 关键字，以指定应为给定配置链接哪个库。这些关键字由 target_link_libraries() 命令使用。如果尚未设置构建配置，或者所使用的生成器不支持构建配置，则此变量值将不包含这些关键字。

<basename>_LIBRARIES

设置为与 <basename>_LIBRARY 变量相同值的结果变量。

注意

select_library_configurations() 命令应在处理标准查找模块参数之前，使用 find_package_handle_standard_args() 进行调用，以确保 <PackageName>_FOUND 结果变量根据 <basename>_LIBRARY 或其他相关变量正确设置。

示例

在查找模块文件中基于构建配置设置库变量

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

当查找模块提供具有多种构建配置的组件时

FindFoo.cmake

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

项目随后可以按如下方式使用此查找模块

CMakeLists.txt

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