From dfd6af04605a25378023244bfad307638d329731 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sun, 16 Mar 2025 00:23:14 +0100 Subject: [PATCH] SelectLibraryConfigurations: Update documentation This describes the module in more details and adds examples section. --- Modules/SelectLibraryConfigurations.cmake | 133 ++++++++++++++++++---- 1 file changed, 112 insertions(+), 21 deletions(-) diff --git a/Modules/SelectLibraryConfigurations.cmake b/Modules/SelectLibraryConfigurations.cmake index 72273678f3..46d9dbe984 100644 --- a/Modules/SelectLibraryConfigurations.cmake +++ b/Modules/SelectLibraryConfigurations.cmake @@ -5,35 +5,126 @@ SelectLibraryConfigurations --------------------------- +This module is intended to be used in :ref:`Find Modules` when finding packages +that are available with multiple :ref:`Build Configurations`. It provides a +macro that automatically sets and adjusts library variables. Supported library +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 + ``_LIBRARIES`` result variable was used for linking found + packages. When writing standard find modules, :ref:`Imported Targets` should + be preferred. In addition to or as an alternative to this module, imported + targets provide finer control over linking through the + :prop_tgt:`IMPORTED_CONFIGURATIONS` property. + +.. command:: select_library_configurations + + .. code-block:: cmake + + select_library_configurations() + + This macro is a helper for setting the ``_LIBRARY`` and + ``_LIBRARIES`` result variables when a library might be provided + with multiple build configurations. + + The argument is: + + ```` + 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.cmake`` module + filename, or the component name, when find module provides them. + + Prior to calling this macro the following cache variables should be set in the + find module (for example, by the :command:`find_library` command): + + ``_LIBRARY_RELEASE`` + A cache variable storing the full path to the ``Release`` build of the + library. If not set or found, this macro will set its value to + ``_LIBRARY_RELEASE-NOTFOUND``. + + ``_LIBRARY_DEBUG`` + A cache variable storing the full path to the ``Debug`` build of the + library. If not set or found, this macro will set its value to + ``_LIBRARY_DEBUG-NOTFOUND``. + + This macro then sets the following local result variables: + + ``_LIBRARY`` + A result variable that is set to the value of + ``_LIBRARY_RELEASE`` variable if found, otherwise it is set to the + value of ``_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 ``_LIBRARY-NOTFOUND``. + + If the :manual:`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 :command:`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. + + ``_LIBRARIES`` + A result variable that is set to the same value as the + ``_LIBRARY`` variable. + + .. note:: + + The ``select_library_configurations()`` macro should be called before + handling standard find module arguments with + :module:`find_package_handle_standard_args() + ` to ensure that the ``_FOUND`` + result variable is correctly set based on ``_LIBRARY`` or other + related variables. + +Examples +^^^^^^^^ + +Setting library variables based on the build configuration inside a find module +file: + .. code-block:: cmake + :caption: FindFoo.cmake - select_library_configurations(basename) + # Find release and debug build of the library + find_library(Foo_LIBRARY_RELEASE ...) + find_library(Foo_LIBRARY_DEBUG ...) -This macro takes a library base name as an argument, and will choose -good values for the variables + # 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 ... + ) - basename_LIBRARY - basename_LIBRARIES - basename_LIBRARY_DEBUG - basename_LIBRARY_RELEASE +When find module provides components with multiple build configurations: -depending on what has been found and set. +.. code-block:: cmake + :caption: FindFoo.cmake -If only ``basename_LIBRARY_RELEASE`` is defined, ``basename_LIBRARY`` will -be set to the release value, and ``basename_LIBRARY_DEBUG`` will be set -to ``basename_LIBRARY_DEBUG-NOTFOUND``. If only ``basename_LIBRARY_DEBUG`` -is defined, then ``basename_LIBRARY`` will take the debug value, and -``basename_LIBRARY_RELEASE`` will be set to ``basename_LIBRARY_RELEASE-NOTFOUND``. + include(SelectLibraryConfigurations) + foreach(component IN LISTS Foo_FIND_COMPONENTS) + # ... + select_library_configurations(Foo_${component}) + # ... + endforeach() -If the generator supports configuration types, then ``basename_LIBRARY`` -and ``basename_LIBRARIES`` will be set with debug and optimized flags -specifying the library to be used for the given configuration. If no -build type has been set or the generator in use does not support -configuration types, then ``basename_LIBRARY`` and ``basename_LIBRARIES`` -will take only the release value, or the debug value if the release one -is not set. +A project can then use this find module as follows: + +.. code-block:: cmake + :caption: CMakeLists.txt + + find_package(Foo) + target_link_libraries(project_target PRIVATE ${Foo_LIBRARIES}) + # ... #]=======================================================================] # This macro was adapted from the FindQt4 CMake module and is maintained by Will