From 151666f5230cca6d7e96f0aa5f00e4f78e2b5403 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Thu, 15 May 2025 07:06:15 +0200 Subject: [PATCH] SelectLibraryConfigurations: Add intro code block - Added intro code block showing how to include this module. - Used "command" instead of "macro". --- Modules/SelectLibraryConfigurations.cmake | 52 ++++++++++++++--------- 1 file changed, 33 insertions(+), 19 deletions(-) diff --git a/Modules/SelectLibraryConfigurations.cmake b/Modules/SelectLibraryConfigurations.cmake index 46d9dbe984..e26c9080aa 100644 --- a/Modules/SelectLibraryConfigurations.cmake +++ b/Modules/SelectLibraryConfigurations.cmake @@ -5,11 +5,18 @@ 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. +This module is intended for use in :ref:`Find Modules` and provides a +command to automatically set library variables when package is available +with multiple :ref:`Build Configurations`. + +Load it in a CMake find module with: + +.. code-block:: cmake + + include(SelectLibraryConfigurations) + +Supported build configurations are ``Release`` and ``Debug`` as these are +the most common ones in such packages. .. note:: @@ -20,13 +27,21 @@ ones in such packages. targets provide finer control over linking through the :prop_tgt:`IMPORTED_CONFIGURATIONS` property. +Commands +^^^^^^^^ + +This module provides the following command: + .. command:: select_library_configurations + Sets and adjusts library variables based on debug and release build + configurations: + .. code-block:: cmake select_library_configurations() - This macro is a helper for setting the ``_LIBRARY`` and + This command is a helper for setting the ``_LIBRARY`` and ``_LIBRARIES`` result variables when a library might be provided with multiple build configurations. @@ -37,20 +52,20 @@ ones in such packages. 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): + Prior to calling this command 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. If not set or found, this command 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. If not set or found, this command will set its value to ``_LIBRARY_DEBUG-NOTFOUND``. - This macro then sets the following local result variables: + This command then sets the following local result variables: ``_LIBRARY`` A result variable that is set to the value of @@ -74,12 +89,11 @@ ones in such packages. .. note:: - The ``select_library_configurations()`` macro should be called before + The ``select_library_configurations()`` command 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. + :command:`find_package_handle_standard_args` to ensure that the + ``_FOUND`` result variable is correctly set based on + ``_LIBRARY`` or other related variables. Examples ^^^^^^^^ @@ -88,7 +102,7 @@ Setting library variables based on the build configuration inside a find module file: .. code-block:: cmake - :caption: FindFoo.cmake + :caption: ``FindFoo.cmake`` # Find release and debug build of the library find_library(Foo_LIBRARY_RELEASE ...) @@ -108,7 +122,7 @@ file: When find module provides components with multiple build configurations: .. code-block:: cmake - :caption: FindFoo.cmake + :caption: ``FindFoo.cmake`` include(SelectLibraryConfigurations) foreach(component IN LISTS Foo_FIND_COMPONENTS) @@ -120,7 +134,7 @@ When find module provides components with multiple build configurations: A project can then use this find module as follows: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(Foo) target_link_libraries(project_target PRIVATE ${Foo_LIBRARIES})