|
|
@@ -376,26 +376,25 @@ 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"
|
|
|
+ "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"
|
|
|
" 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"
|
|
|
+ "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"
|
|
|
"See the cmake_policy() command documentation for discussion of the "
|
|
|
"NO_POLICY_SCOPE option."
|
Brad King