Add a way to exclude INTERFACE properties from exported targets.

Projects set interface requirements upstream, and existing
downstreams use of target_link_libraries will consume those interfaces.

This can create a backward compatibility concern as the result may
be changing the order of include directories of downstreams, or another
side-effect of using the INTERFACE properties.

Provide a way for them to emulate the behavior of a version-based
policy in the config file.

1 files changed, 21 insertions, 0 deletions

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index 470ceca..e9b6ab6 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -376,6 +376,27 @@ void cmFindPackageCommand::GenerateDocumentation()
     "The package configuration file may set <package>_FOUND to false "
     "to tell find_package that component requirements are not satisfied."
     "\n"
+    "Targets exported by the install() command may have additional INTERFACE "
+    "properties set for include directories, compile definitions etc.  As "
+    "these may create a backward compatibility concern for consumers of "
+    "existing projects, it is possible to set the <package>_NO_INTERFACES "
+    "variable to disable populating those interfaces.  It is possible to "
+    "emulate a version-based policy for whether the interfaces should be "
+    "enabled in the config file before including the imported targets file. "
+    "This allows consumers to decide when to enable the new interfaces when "
+    "upgrading.  The upstream project is responsible for adding code similar "
+    "to this in the version which generates the INTERFACE content:\n"
+    "  if(${CMAKE_FIND_PACKAGE_NAME}_FIND_VERSION VERSION_LESS 2.3\n"
+    "      AND NOT ${CMAKE_FIND_PACKAGE_NAME}_INTERFACES)\n"
+    "    set(${CMAKE_FIND_PACKAGE_NAME}_NO_INTERFACES 1)\n"
+    "  endif()\n"
+    "  include(\"${CMAKE_CURRENT_LIST_DIR}/<package>Targets.cmake\")\n"
+    "\n"
+    "Downstream users may then choose to use the new interfaces by finding "
+    "the newer version of upstream.  They can also choose to not use the new "
+    "interfaces by setting <package>_INTERFACES to false before finding the "
+    "package.\n"
+    "\n"
     "See the cmake_policy() command documentation for discussion of the "
     "NO_POLICY_SCOPE option."
     ;