CMakePackageConfigHelpers: Add version range support

Help/release/dev/CMakePackageConfigHelpers-version_range.rst

+CMakePackageConfigHelpers-version_range
+---------------------------------------
+
+* :module:`CMakePackageConfigHelpers` module learned to manage version range.

Modules/BasicConfigVersion-AnyNewerVersion.cmake.in

@@ -9,12 +9,23 @@
 
 set(PACKAGE_VERSION "@CVF_VERSION@")
 
-if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION)
-  set(PACKAGE_VERSION_COMPATIBLE FALSE)
+if (PACKAGE_FIND_VERSION_RANGE)
+  # Package version must be in the requested version range
+  if ((PACKAGE_FIND_VERSION_RANGE_MIN STREQUAL "INCLUDE" AND PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION_MIN)
+      OR ((PACKAGE_FIND_VERSION_RANGE_MAX STREQUAL "INCLUDE" AND PACKAGE_VERSION VERSION_GREATER PACKAGE_FIND_VERSION_MAX)
+        OR (PACKAGE_FIND_VERSION_RANGE_MAX STREQUAL "EXCLUDE" AND PACKAGE_VERSION VERSION_GREATER_EQUAL PACKAGE_FIND_VERSION_MAX)))
+    set(PACKAGE_VERSION_COMPATIBLE FALSE)
+  else()
+    set(PACKAGE_VERSION_COMPATIBLE TRUE)
+  endif()
 else()
-  set(PACKAGE_VERSION_COMPATIBLE TRUE)
-  if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
-    set(PACKAGE_VERSION_EXACT TRUE)
+  if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION)
+    set(PACKAGE_VERSION_COMPATIBLE FALSE)
+  else()
+    set(PACKAGE_VERSION_COMPATIBLE TRUE)
+    if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
+      set(PACKAGE_VERSION_EXACT TRUE)
+    endif()
   endif()
 endif()
 

Modules/BasicConfigVersion-ExactVersion.cmake.in

@@ -9,6 +9,13 @@
 # The variable CVF_VERSION must be set before calling configure_file().
 
 
+if (PACKAGE_FIND_VERSION_RANGE)
+  message(AUTHOR_WARNING
+    "`find_package()` specify a version range but the version strategy "
+    "(ExactVersion) of the module `${PACKAGE_FIND_NAME}` is incompatible "
+    "with this request. Only the lower endpoint of the range will be used.")
+endif()
+
 set(PACKAGE_VERSION "@CVF_VERSION@")
 
 if("@CVF_VERSION@" MATCHES "^([0-9]+\\.[0-9]+\\.[0-9]+)\\.") # strip the tweak version

Modules/BasicConfigVersion-SameMajorVersion.cmake.in

@@ -9,6 +9,13 @@
 # The variable CVF_VERSION must be set before calling configure_file().
 
 
+if (PACKAGE_FIND_VERSION_RANGE)
+  message(AUTHOR_WARNING
+    "`find_package()` specify a version range but the version strategy "
+    "(SameMajorVersion) of the module `${PACKAGE_FIND_NAME}` is incompatible "
+    "with this request. Only the lower endpoint of the range will be used.")
+endif()
+
 set(PACKAGE_VERSION "@CVF_VERSION@")
 
 if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION)

Modules/BasicConfigVersion-SameMinorVersion.cmake.in

@@ -10,6 +10,13 @@
 # The variable CVF_VERSION must be set before calling configure_file().
 
 
+if (PACKAGE_FIND_VERSION_RANGE)
+  message(AUTHOR_WARNING
+    "`find_package()` specify a version range but the version strategy "
+    "(SameMinorVersion) of the module `${PACKAGE_FIND_NAME}` is incompatible "
+    "with this request. Only the lower endpoint of the range will be used.")
+endif()
+
 set(PACKAGE_VERSION "@CVF_VERSION@")
 
 if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION)

Modules/CMakePackageConfigHelpers.cmake

@@ -159,6 +159,11 @@ If your project has more elaborated version matching rules, you will need to
 write your own custom ``ConfigVersion.cmake`` file instead of using this
 macro.
 
+.. note:: ``COMPATIBILITY_MODE`` ``AnyNewerVersion`` handles the version range
+  if any is specified (see :command:`find_package` command for the details).
+  All other modes are incompatible with version range and will display an
+  author warning if a one is specified.
+
 If ``ARCH_INDEPENDENT`` is given, the installed package version will be
 considered compatible even if it was built for a different architecture than
 the requested architecture.  Otherwise, an architecture check will be performed,

Tests/ExportImport/Import/CMakeLists.txt

@@ -23,3 +23,6 @@ add_subdirectory(try_compile)
 
 # Test package INTERFACE controls
 add_subdirectory(Interface)
+
+# Test package version range
+add_subdirectory(version_range)

Tests/ExportImport/Import/version_range/CMakeLists.txt

+
+cmake_minimum_required(VERSION 3.18)
+
+find_package(testLibRequired 2.0...3.0)
+
+if (NOT testLibRequired_FOUND)
+  message(SEND_ERROR "version_range: fail to find package testLibRequired(2.5) with range 2.0...3.0")
+endif()
+
+
+find_package(testLibRequired 2.0...<2.5)
+
+if (testLibRequired_FOUND)
+  message(SEND_ERROR "version_range: package testLibRequired(2.5) unexpectedly found with range 2.0...<2.5")
+endif()