Help: Document the target properties exported to IMPORTED targets.

2 files changed, 24 insertions, 0 deletions

diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index be60ebb..03f9115 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -218,6 +218,8 @@ each keyword:
     PRIVATE serialization
   )
 
+.. _`Compatible Interface Properties`:
+
 Compatible Interface Properties
 -------------------------------
 
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 3eda829..b572bf7 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -280,6 +280,12 @@ shared library:
 
   add_library(ClimbingStats SHARED climbingstats.cpp)
   generate_export_header(ClimbingStats)
+  set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
+  set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
+  set_property(TARGET ClimbingStats PROPERTY INTERFACE_ClimbingStats_MAJOR_VERSION 3)
+  set_property(TARGET ClimbingStats APPEND PROPERTY
+    COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
+  )
 
   install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
     LIBRARY DESTINATION lib
@@ -346,6 +352,22 @@ targets, suitable for use by downsteams and arranges to install it to
 and a ``cmake/ClimbingStatsConfig.cmake`` are installed to the same location,
 completing the package.
 
+The generated :prop_tgt:`IMPORTED` targets have appropriate properties set
+to define their usage requirements, such as
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
+:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and other relevant built-in
+``INTERFACE_`` properties.  The ``INTERFACE`` variant of user-defined
+properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and
+other :ref:`Compatible Interface Properties` are also propagated to the
+generated :prop_tgt:`IMPORTED` targets.  In the above case,
+``ClimbingStats_MAJOR_VERSION`` is defined as a string which must be
+compatible among the dependencies of any depender.  By setting this custom
+defined user property in this version and in the next version of
+``ClimbingStats``, :manual:`cmake(1)` will issue a diagnostic if there is an
+attempt to use version 3 together with version 4.  Packages can choose to
+employ such a pattern if different major versions of the package are designed
+to be incompatible.
+
 A ``NAMESPACE`` with double-colons is specified when exporting the targets
 for installation.  This convention of double-colons gives CMake a hint that
 the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams