Help: Document IMPORTED_CONFIGURATIONS target property for Find modules.

This commit is contained in:
Stephen Kelly 2014-12-04 23:56:21 +01:00
parent f0d0d761b2
commit e18e21aeb5
1 changed files with 40 additions and 1 deletions

View File

@ -876,7 +876,10 @@ To prevent users being overwhelmed with settings to configure, try to
keep as many options as possible out of the cache, leaving at least one keep as many options as possible out of the cache, leaving at least one
option which can be used to disable use of the module, or locate a option which can be used to disable use of the module, or locate a
not-found library (e.g. ``Xxx_ROOT_DIR``). For the same reason, mark not-found library (e.g. ``Xxx_ROOT_DIR``). For the same reason, mark
most cache options as advanced. most cache options as advanced. For packages which provide both debug
and release binaries, it is common to create cache variables with a
``_LIBRARY_<CONFIG>`` suffix, such as ``Foo_LIBRARY_RELEASE`` and
``Foo_LIBRARY_DEBUG``.
While these are the standard variable names, you should provide While these are the standard variable names, you should provide
backwards compatibility for any old names that were actually in use. backwards compatibility for any old names that were actually in use.
@ -1049,6 +1052,42 @@ not any of its dependencies. Instead, those dependencies should also be
targets, and CMake should be told that they are dependencies of this target. targets, and CMake should be told that they are dependencies of this target.
CMake will then combine all the necessary information automatically. CMake will then combine all the necessary information automatically.
If the library is available with multiple configurations, the
:prop_tgt:`IMPORTED_CONFIGURATIONS` target property should also be
populated:
.. code-block:: cmake
if(Foo_FOUND)
if (NOT TARGET Foo::Foo)
add_library(Foo::Foo UNKNOWN IMPORTED)
endif()
if (Foo_LIBRARY_RELEASE)
set_property(TARGET Foo::Foo APPEND PROPERTY
IMPORTED_CONFIGURATIONS RELEASE
)
set_target_properties(Foo::Foo PROPERTIES
IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}"
)
endif()
if (Foo_LIBRARY_DEBUG)
set_property(TARGET Foo::Foo APPEND PROPERTY
IMPORTED_CONFIGURATIONS DEBUG
)
set_target_properties(Foo::Foo PROPERTIES
IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}"
)
endif()
set_target_properties(Foo::Foo PROPERTIES
INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}"
INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}"
)
endif()
The ``RELEASE`` variant should be listed first in the property
so that that variant is chosen if the user uses a configuration which is
not an exact match for any listed ``IMPORTED_CONFIGURATIONS``.
We should also provide some information about the package, such as where to We should also provide some information about the package, such as where to
download it. download it.