|
|
@@ -376,25 +376,26 @@ void cmFindPackageCommand::GenerateDocumentation()
|
|
|
"The package configuration file may set <package>_FOUND to false "
|
|
|
"to tell find_package that component requirements are not satisfied."
|
|
|
"\n"
|
|
|
- "A package configuration file may include() a <package>Targets.cmake "
|
|
|
- "file, created by install(EXPORT) in the upstream source, to import "
|
|
|
- "targets into the downstream consumer. "
|
|
|
- "When a new version of the upstream adds INTERFACE properties not "
|
|
|
- "present in a previous version it can change behavior for existing "
|
|
|
- "downstreams. "
|
|
|
- "In order to remain source compatible the upstream package configuration "
|
|
|
- "file may set <package>_NO_INTERFACES to disable INTERFACE properties. "
|
|
|
- "For example, code of the form:\n"
|
|
|
- " if(<package>_FIND_VERSION VERSION_LESS <new-version>\n"
|
|
|
- " AND NOT <package>_INTERFACES)\n"
|
|
|
- " set(<package>_NO_INTERFACES 1)\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"
|
|
|
- "tells <package>Targets.cmake not to provide the INTERFACE properties "
|
|
|
- "unless the downstream requests at least <new-version> or sets "
|
|
|
- "<package>_INTERFACES to explicitly request them. "
|
|
|
- "This allows consumers to decide when to enable the new interfaces when "
|
|
|
- "upgrading."
|
|
|
+ "\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."
|
Stephen Kelly