diff options
Diffstat (limited to 'Source/cmFindPackageCommand.cxx')
| -rw-r--r-- | Source/cmFindPackageCommand.cxx | 35 |
1 files changed, 18 insertions, 17 deletions
diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx index 6e78bd7..e9b6ab6 100644 --- a/Source/cmFindPackageCommand.cxx +++ b/Source/cmFindPackageCommand.cxx @@ -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." |