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.

Source/cmExportFileGenerator.cxx

@@ -264,15 +264,16 @@ void cmExportFileGenerator::GenerateInterfaceProperties(cmTarget *target,
 {
   if (!properties.empty())
     {
+    os << "if(NOT ${CMAKE_FIND_PACKAGE_NAME}_NO_INTERFACES)\n";
     std::string targetName = this->Namespace;
     targetName += target->GetName();
-    os << "set_target_properties(" << targetName << " PROPERTIES\n";
+    os << "  set_target_properties(" << targetName << " PROPERTIES\n";
     for(ImportPropertyMap::const_iterator pi = properties.begin();
         pi != properties.end(); ++pi)
       {
-      os << "  " << pi->first << " \"" << pi->second << "\"\n";
+      os << "    " << pi->first << " \"" << pi->second << "\"\n";
       }
-    os << ")\n\n";
+    os << "  )\nendif()\n\n";
     }
 }
 

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."
     ;