FPHSA: add support of version range

Help/release/dev/FPHSA-version_range.rst

@@ -0,0 +1,7 @@
+FPHSA-version_range
+-------------------
+
+* The :module:`FindPackageHandleStandardArgs` module learned to handle
+  version range. It also gained the ``find_package_check_version()`` command to
+  check the validity of a version against version-related arguments of
+  :command:`find_package` command.

Modules/FindPackageHandleStandardArgs.cmake

@@ -5,16 +5,19 @@
 FindPackageHandleStandardArgs
 -----------------------------
 
-This module provides a function intended to be used in :ref:`Find Modules`
-implementing :command:`find_package(<PackageName>)` calls.  It handles the
-``REQUIRED``, ``QUIET`` and version-related arguments of ``find_package``.
-It also sets the ``<PackageName>_FOUND`` variable.  The package is
-considered found if all variables listed contain valid results, e.g.
-valid filepaths.
+This module provides functions intended to be used in :ref:`Find Modules`
+implementing :command:`find_package(<PackageName>)` calls.
 
 .. command:: find_package_handle_standard_args
 
-  There are two signatures::
+  This command handles the ``REQUIRED``, ``QUIET`` and version-related
+  arguments of :command:`find_package`.  It also sets the
+  ``<PackageName>_FOUND`` variable.  The package is considered found if all
+  variables listed contain valid results, e.g. valid filepaths.
+
+  There are two signatures:
+
+  .. code-block:: cmake
 
     find_package_handle_standard_args(<PackageName>
       (DEFAULT_MSG|<custom-failure-message>)
@@ -25,6 +28,7 @@ valid filepaths.
       [FOUND_VAR <result-var>]
       [REQUIRED_VARS <required-var>...]
       [VERSION_VAR <version-var>]
+      [HANDLE_VERSION_RANGE]
       [HANDLE_COMPONENTS]
       [CONFIG_MODE]
       [NAME_MISMATCHED]
@@ -69,6 +73,11 @@ valid filepaths.
     version and the version which has been actually found, both
     if the version is ok or not.
 
+  ``HANDLE_VERSION_RANGE``
+    Enable handling of a version range, if one is specified. Without this
+    option, a developer warning will be displayed if a version range is
+    specified.
+
   ``HANDLE_COMPONENTS``
     Enable handling of package components.  In this case, the command
     will report which components have been found and which are missing,
@@ -151,10 +160,54 @@ In this case, a ``FindAutmoc4.cmake`` module wraps a call to
 directory for ``automoc4``.  Then the call to
 ``find_package_handle_standard_args`` produces a proper success/failure
 message.
+
+.. command:: find_package_check_version
+
+  Helper function which can be used to check if a ``<version>`` is valid
+  against version-related arguments of :command:`find_package`.
+
+  .. code-block:: cmake
+
+    find_package_check_version(<version> <result-var>
+      [HANDLE_VERSION_RANGE]
+      [RESULT_MESSAGE_VARIABLE <message-var>]
+      )
+
+  The ``<result-var>`` will hold a boolean value giving the result of the check.
+
+  The options are:
+
+  ``HANDLE_VERSION_RANGE``
+    Enable handling of a version range, if one is specified. Without this
+    option, a developer warning will be displayed if a version range is
+    specified.
+
+  ``RESULT_MESSAGE_VARIABLE <message-var>``
+    Specify a variable to get back a message describing the result of the check.
+
+Example for the usage:
+
+.. code-block:: cmake
+
+  find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
+    RESULT_MESSAGE_VARIABLE reason)
+  if (result)
+    message (STATUS "${reason}")
+  else()
+    message (FATAL_ERROR "${reason}")
+  endif()
 #]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/FindPackageMessage.cmake)
 
+
+cmake_policy(PUSH)
+# numbers and boolean constants
+cmake_policy (SET CMP0012 NEW)
+# IN_LIST operator
+cmake_policy (SET CMP0057 NEW)
+
+
 # internal helper macro
 macro(_FPHSA_FAILURE_MESSAGE _msg)
   set (__msg "${_msg}")
@@ -207,10 +260,112 @@ macro(_FPHSA_HANDLE_FAILURE_CONFIG_MODE)
 endmacro()
 
 
+function(FIND_PACKAGE_CHECK_VERSION version result)
+  cmake_parse_arguments (PARSE_ARGV 2 FPCV "HANDLE_VERSION_RANGE;NO_AUTHOR_WARNING_VERSION_RANGE" "RESULT_MESSAGE_VARIABLE" "")
+
+  if (FPCV_UNPARSED_ARGUMENTS)
+    message (FATAL_ERROR "find_package_check_version(): ${FPCV_UNPARSED_ARGUMENTS}: unexpected arguments")
+  endif()
+  if ("RESULT_MESSAGE_VARIABLE" IN_LIST FPCV_KEYWORDS_MISSING_VALUES)
+    message (FATAL_ERROR "find_package_check_version(): RESULT_MESSAGE_VARIABLE expects an argument")
+  endif()
+
+  set (${result} FALSE PARENT_SCOPE)
+  if (FPCV_RESULT_MESSAGE_VARIABLE)
+    unset (${FPCV_RESULT_MESSAGE_VARIABLE} PARENT_SCOPE)
+  endif()
+
+  if (CMAKE_FIND_PACKAGE_NAME)
+    set (package ${CMAKE_FIND_PACKAGE_NAME})
+  else()
+    message (FATAL_ERROR "find_package_check_version(): Cannot be used outside a 'Find Module'")
+  endif()
+
+  if (NOT FPCV_NO_AUTHOR_WARNING_VERSION_RANGE
+      AND ${package}_FIND_VERSION_RANGE AND NOT FPCV_HANDLE_VERSION_RANGE)
+    message(AUTHOR_WARNING
+      "`find_package()` specify a version range but the option "
+      "HANDLE_VERSION_RANGE` is not passed to `find_package_check_version()`. "
+      "Only the lower endpoint of the range will be used.")
+  endif()
+
+
+  set (version_ok FALSE)
+  unset (version_msg)
+
+  if (FPCV_HANDLE_VERSION_RANGE AND ${package}_FIND_VERSION_RANGE)
+    if (${package}_FIND_VERSION_MIN VERSION_GREATER ${package}_FIND_VERSION_MAX
+        OR (${package}_FIND_VERSION_MIN VERSION_EQUAL ${package}_FIND_VERSION_MAX
+          AND ${package}_FIND_VERSION_RANGE_MAX STREQUAL "EXCLUDE"))
+      set (version_msg "Found unsuitable version \"${version}\", required range is empty (\"${${package}_FIND_VERSION_RANGE}\")")
+    elseif ((${package}_FIND_VERSION_RANGE_MIN STREQUAL "INCLUDE"
+            AND version VERSION_GREATER_EQUAL ${package}_FIND_VERSION_MIN)
+        AND ((${package}_FIND_VERSION_RANGE_MAX STREQUAL "INCLUDE"
+            AND version VERSION_LESS_EQUAL ${package}_FIND_VERSION_MAX)
+          OR (${package}_FIND_VERSION_RANGE_MAX STREQUAL "EXCLUDE"
+              AND version VERSION_LESS ${package}_FIND_VERSION_MAX)))
+      set (version_ok TRUE)
+      set(version_msg "(found suitable version \"${version}\", required range is \"${${package}_FIND_VERSION_RANGE}\")")
+    else()
+      set(version_msg "Found unsuitable version \"${version}\", required range is \"${${package}_FIND_VERSION_RANGE}\"")
+    endif()
+  elseif (DEFINED ${package}_FIND_VERSION)
+    if(${package}_FIND_VERSION_EXACT)       # exact version required
+      # count the dots in the version string
+      string(REGEX REPLACE "[^.]" "" version_dots "${version}")
+      # add one dot because there is one dot more than there are components
+      string(LENGTH "${version_dots}." version_dots)
+      if (version_dots GREATER ${package}_FIND_VERSION_COUNT)
+        # Because of the C++ implementation of find_package() ${package}_FIND_VERSION_COUNT
+        # is at most 4 here. Therefore a simple lookup table is used.
+        if (${package}_FIND_VERSION_COUNT EQUAL 1)
+          set(version_regex "[^.]*")
+        elseif (${package}_FIND_VERSION_COUNT EQUAL 2)
+          set(version_regex "[^.]*\\.[^.]*")
+        elseif (${package}_FIND_VERSION_COUNT EQUAL 3)
+          set(version_regex "[^.]*\\.[^.]*\\.[^.]*")
+        else()
+          set(version_regex "[^.]*\\.[^.]*\\.[^.]*\\.[^.]*")
+        endif()
+        string(REGEX REPLACE "^(${version_regex})\\..*" "\\1" version_head "${version}")
+        if (NOT ${package}_FIND_VERSION VERSION_EQUAL version_head)
+          set(version_msg "Found unsuitable version \"${version}\", but required is exact version \"${${package}_FIND_VERSION}\"")
+        else ()
+          set(version_ok TRUE)
+          set(version_msg "(found suitable exact version \"${_FOUND_VERSION}\")")
+        endif ()
+      else ()
+        if (NOT ${package}_FIND_VERSION VERSION_EQUAL version)
+          set(version_msg "Found unsuitable version \"${version}\", but required is exact version \"${${package}_FIND_VERSION}\"")
+        else ()
+          set(version_ok TRUE)
+          set(version_msg "(found suitable exact version \"${version}\")")
+        endif ()
+      endif ()
+    else()     # minimum version
+      if (${package}_FIND_VERSION VERSION_GREATER version)
+        set(version_msg "Found unsuitable version \"${version}\", but required is at least \"${${package}_FIND_VERSION}\"")
+      else()
+        set(version_ok TRUE)
+        set(version_msg "(found suitable version \"${version}\", minimum required is \"${${package}_FIND_VERSION}\")")
+      endif()
+    endif()
+  else ()
+    set(version_ok TRUE)
+    set(version_msg "(found version \"${version}\")")
+  endif()
+
+  set (${result} ${version_ok} PARENT_SCOPE)
+  if (FPCV_RESULT_MESSAGE_VARIABLE)
+    set (${FPCV_RESULT_MESSAGE_VARIABLE} "${version_msg}" PARENT_SCOPE)
+  endif()
+endfunction()
+
+
 function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
 
   # Set up the arguments for `cmake_parse_arguments`.
-  set(options  CONFIG_MODE  HANDLE_COMPONENTS NAME_MISMATCHED)
+  set(options  CONFIG_MODE  HANDLE_COMPONENTS NAME_MISMATCHED HANDLE_VERSION_RANGE)
   set(oneValueArgs  FAIL_MESSAGE  REASON_FAILURE_MESSAGE VERSION_VAR  FOUND_VAR)
   set(multiValueArgs REQUIRED_VARS)
 
@@ -278,7 +433,14 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
       "to follow a certain pattern.")
   endif ()
 
-# now that we collected all arguments, process them
+  if (${_NAME}_FIND_VERSION_RANGE AND NOT FPHSA_HANDLE_VERSION_RANGE)
+    message(AUTHOR_WARNING
+      "`find_package()` specify a version range but the module ${_NAME} does "
+      "not support this capability. Only the lower endpoint of the range "
+      "will be used.")
+  endif()
+
+  # now that we collected all arguments, process them
 
   if("x${FPHSA_FAIL_MESSAGE}" STREQUAL "xDEFAULT_MSG")
     set(FPHSA_FAIL_MESSAGE "Could NOT find ${_NAME}")
@@ -364,61 +526,22 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
   if (DEFINED ${_NAME}_FIND_VERSION)
     if(DEFINED ${FPHSA_VERSION_VAR})
       set(_FOUND_VERSION ${${FPHSA_VERSION_VAR}})
-
-      if(${_NAME}_FIND_VERSION_EXACT)       # exact version required
-        # count the dots in the version string
-        string(REGEX REPLACE "[^.]" "" _VERSION_DOTS "${_FOUND_VERSION}")
-        # add one dot because there is one dot more than there are components
-        string(LENGTH "${_VERSION_DOTS}." _VERSION_DOTS)
-        if (_VERSION_DOTS GREATER ${_NAME}_FIND_VERSION_COUNT)
-          # Because of the C++ implementation of find_package() ${_NAME}_FIND_VERSION_COUNT
-          # is at most 4 here. Therefore a simple lookup table is used.
-          if (${_NAME}_FIND_VERSION_COUNT EQUAL 1)
-            set(_VERSION_REGEX "[^.]*")
-          elseif (${_NAME}_FIND_VERSION_COUNT EQUAL 2)
-            set(_VERSION_REGEX "[^.]*\\.[^.]*")
-          elseif (${_NAME}_FIND_VERSION_COUNT EQUAL 3)
-            set(_VERSION_REGEX "[^.]*\\.[^.]*\\.[^.]*")
-          else ()
-            set(_VERSION_REGEX "[^.]*\\.[^.]*\\.[^.]*\\.[^.]*")
-          endif ()
-          string(REGEX REPLACE "^(${_VERSION_REGEX})\\..*" "\\1" _VERSION_HEAD "${_FOUND_VERSION}")
-          unset(_VERSION_REGEX)
-          if (NOT ${_NAME}_FIND_VERSION VERSION_EQUAL _VERSION_HEAD)
-            set(VERSION_MSG "Found unsuitable version \"${_FOUND_VERSION}\", but required is exact version \"${${_NAME}_FIND_VERSION}\"")
-            set(VERSION_OK FALSE)
-          else ()
-            set(VERSION_MSG "(found suitable exact version \"${_FOUND_VERSION}\")")
-          endif ()
-          unset(_VERSION_HEAD)
-        else ()
-          if (NOT ${_NAME}_FIND_VERSION VERSION_EQUAL _FOUND_VERSION)
-            set(VERSION_MSG "Found unsuitable version \"${_FOUND_VERSION}\", but required is exact version \"${${_NAME}_FIND_VERSION}\"")
-            set(VERSION_OK FALSE)
-          else ()
-            set(VERSION_MSG "(found suitable exact version \"${_FOUND_VERSION}\")")
-          endif ()
-        endif ()
-        unset(_VERSION_DOTS)
-
-      else()     # minimum version specified:
-        if (${_NAME}_FIND_VERSION VERSION_GREATER _FOUND_VERSION)
-          set(VERSION_MSG "Found unsuitable version \"${_FOUND_VERSION}\", but required is at least \"${${_NAME}_FIND_VERSION}\"")
-          set(VERSION_OK FALSE)
-        else ()
-          set(VERSION_MSG "(found suitable version \"${_FOUND_VERSION}\", minimum required is \"${${_NAME}_FIND_VERSION}\")")
-        endif ()
+      if (FPHSA_HANDLE_VERSION_RANGE)
+        set (FPCV_HANDLE_VERSION_RANGE HANDLE_VERSION_RANGE)
+      else()
+        set(FPCV_HANDLE_VERSION_RANGE NO_AUTHOR_WARNING_VERSION_RANGE)
       endif()
-
+      find_package_check_version (${_FOUND_VERSION} VERSION_OK RESULT_MESSAGE_VARIABLE VERSION_MSG
+        ${FPCV_HANDLE_VERSION_RANGE})
     else()
-
       # if the package was not found, but a version was given, add that to the output:
       if(${_NAME}_FIND_VERSION_EXACT)
-         set(VERSION_MSG "(Required is exact version \"${${_NAME}_FIND_VERSION}\")")
+        set(VERSION_MSG "(Required is exact version \"${${_NAME}_FIND_VERSION}\")")
+      elseif (FPHSA_HANDLE_VERSION_RANGE AND ${_NAME}_FIND_VERSION_RANGE)
+        set(VERSION_MSG "(Required is version range \"${${_NAME}_FIND_VERSION_RANGE}\")")
       else()
-         set(VERSION_MSG "(Required is at least version \"${${_NAME}_FIND_VERSION}\")")
+        set(VERSION_MSG "(Required is at least version \"${${_NAME}_FIND_VERSION}\")")
       endif()
-
     endif()
   else ()
     # Check with DEFINED as the found version may be 0.
@@ -464,3 +587,6 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
   set(${_NAME}_FOUND ${${_NAME}_FOUND} PARENT_SCOPE)
   set(${_NAME_UPPER}_FOUND ${${_NAME}_FOUND} PARENT_SCOPE)
 endfunction()
+
+
+cmake_policy(POP)

Tests/RunCMake/FPHSA/FindPseudoRange.cmake

@@ -0,0 +1,7 @@
+# pseudo find_module
+
+set(FOOBAR TRUE)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(PseudoRange REQUIRED_VARS FOOBAR VERSION_VAR PseudoRange_VERSION
+                                  HANDLE_VERSION_RANGE)

Tests/RunCMake/FPHSA/RunCMakeTest.cmake

@@ -55,3 +55,15 @@ run_cmake(required_and_optional_components)
 run_cmake(all_optional_components)
 list(APPEND RunCMake_TEST_OPTIONS "-DUseComponents_REQUIRE_VARS=TRUE")
 run_cmake(required_components_with_vars)
+
+# check handling of version range
+set(RunCMake_TEST_OPTIONS "-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_LIST_DIR}" "-DPseudo_VERSION=2.3.4.5")
+run_cmake(range_ignored)
+set(RunCMake_TEST_OPTIONS "-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_LIST_DIR}" "-DPseudoRange_VERSION=2.0")
+run_cmake(range_no-range)
+run_cmake(range_empty-1)
+run_cmake(range_empty-2)
+run_cmake(range_1-3)
+run_cmake(range_1-2-include)
+run_cmake(range_1-2-exclude)
+run_cmake(range_3-4)

Tests/RunCMake/FPHSA/range_1-2-exclude-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/range_1-2-exclude-stderr.txt

@@ -0,0 +1,2 @@
+  Could NOT find PseudoRange: Found unsuitable version "2\.0", required range
+  is "1.0...<2.0" \(found TRUE\)

Tests/RunCMake/FPHSA/range_1-2-exclude.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 1.0...<2.0 REQUIRED)

Tests/RunCMake/FPHSA/range_1-2-include.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 1.0...2.0 REQUIRED)

Tests/RunCMake/FPHSA/range_1-3.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 1.0...3.0 REQUIRED)

Tests/RunCMake/FPHSA/range_3-4-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/range_3-4-stderr.txt

@@ -0,0 +1,2 @@
+  Could NOT find PseudoRange: Found unsuitable version "2\.0", required range
+  is "3.0...4.0" \(found TRUE\)

Tests/RunCMake/FPHSA/range_3-4.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 3.0...4.0 REQUIRED)

Tests/RunCMake/FPHSA/range_empty-1-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/range_empty-1-stderr.txt

@@ -0,0 +1,6 @@
+CMake Error at .+FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
+  Could NOT find PseudoRange: Found unsuitable version "2\.0", required range
+  is empty \("3\.0\.\.\.2\.0"\) \(found TRUE\)
+Call Stack \(most recent call first\):
+  .+FindPackageHandleStandardArgs.cmake:[0-9]+ \(_FPHSA_FAILURE_MESSAGE\)
+  FindPseudoRange.cmake:[0-9]+ \(find_package_handle_standard_args\)

Tests/RunCMake/FPHSA/range_empty-1.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 3.0...2.0 REQUIRED)

Tests/RunCMake/FPHSA/range_empty-2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/range_empty-2-stderr.txt

@@ -0,0 +1,6 @@
+CMake Error at .+FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
+  Could NOT find PseudoRange: Found unsuitable version "2\.0", required range
+  is empty \("2\.0\.\.\.<2.0"\) \(found TRUE\)
+Call Stack \(most recent call first\):
+  .+FindPackageHandleStandardArgs.cmake:[0-9]+ \(_FPHSA_FAILURE_MESSAGE\)
+  FindPseudoRange.cmake:[0-9]+ \(find_package_handle_standard_args\)

Tests/RunCMake/FPHSA/range_empty-2.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 2.0...<2.0 REQUIRED)

Tests/RunCMake/FPHSA/range_ignored-stderr.txt

@@ -0,0 +1,4 @@
+CMake Warning \(dev\) at .+FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
+  `find_package\(\)` specify a version range but the module Pseudo does not
+  support this capability.  Only the lower endpoint of the range will be
+  used.

Tests/RunCMake/FPHSA/range_ignored.cmake

@@ -0,0 +1 @@
+find_package(Pseudo 1.0...2.0 REQUIRED)

Tests/RunCMake/FPHSA/range_no-range.cmake

@@ -0,0 +1 @@
+find_package(PseudoRange 1.0 REQUIRED)