SelectLibraryConfigurations: Update documentation

This describes the module in more details and adds examples section.

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
+  ``<PackageName>_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(<basename>)
+
+  This macro 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 macro the following cache variables should be set in the
+  find module (for example, by the :command:`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 macro 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 macro will set its value to
+    ``<basename>_LIBRARY_DEBUG-NOTFOUND``.
+
+  This macro 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 :manual:`CMake Generator <cmake-generators(7)>` 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.
+
+  ``<basename>_LIBRARIES``
+    A result variable that is set to the same value as the
+    ``<basename>_LIBRARY`` variable.
+
+  .. note::
+
+    The ``select_library_configurations()`` macro should be called before
+    handling standard find module arguments with
+    :module:`find_package_handle_standard_args()
+    <FindPackageHandleStandardArgs>` 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:
+
 .. 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