From 3e6466eb16fe1214e367228b8ac937c7ca4bd2de Mon Sep 17 00:00:00 2001
From: Matthew Woehlke <matthew.woehlke@kitware.com>
Date: Wed, 12 Feb 2025 11:33:43 -0500
Subject: find_package: Honor version requests when finding CPS packages

Teach find_package to check a CPS package's version (when provided)
against a version request given to the find_package invocation.
---
 Help/command/find_package.rst                      | 119 ++++++++++++++++-----
 Source/cmFindPackageCommand.cxx                    |  57 ++++++++--
 Source/cmPackageInfoReader.cxx                     |  13 ++-
 Source/cmPackageInfoReader.h                       |  10 +-
 Tests/FindPackageCpsTest/CMakeLists.txt            |  13 ++-
 .../share/cps/SortLib/SortLib.cps                  |   7 ++
 .../RunCMake/find_package-CPS/CompatVersion.cmake  |  13 +++
 .../RunCMake/find_package-CPS/CustomVersion.cmake  |  13 +++
 Tests/RunCMake/find_package-CPS/ExactVersion.cmake |  13 +++
 .../find_package-CPS/MissingVersion1-result.txt    |   1 +
 .../find_package-CPS/MissingVersion1-stderr.txt    |  13 +++
 .../find_package-CPS/MissingVersion1.cmake         |  10 ++
 .../find_package-CPS/MissingVersion2-result.txt    |   1 +
 .../find_package-CPS/MissingVersion2-stderr.txt    |  13 +++
 .../find_package-CPS/MissingVersion2.cmake         |  10 ++
 .../find_package-CPS/MultipleVersions.cmake        |  13 +++
 Tests/RunCMake/find_package-CPS/RunCMakeTest.cmake |  16 +++
 .../find_package-CPS/TransitiveVersion.cmake       |  13 +++
 .../RunCMake/find_package-CPS/VersionLimit1.cmake  |  14 +++
 .../RunCMake/find_package-CPS/VersionLimit2.cmake  |  14 +++
 .../find_package-CPS/VersionLimit3-result.txt      |   1 +
 .../find_package-CPS/VersionLimit3-stderr.txt      |  13 +++
 .../RunCMake/find_package-CPS/VersionLimit3.cmake  |  11 ++
 .../find_package-CPS/VersionLimit4-result.txt      |   1 +
 .../find_package-CPS/VersionLimit4-stderr.txt      |  13 +++
 .../RunCMake/find_package-CPS/VersionLimit4.cmake  |  11 ++
 .../cps/CustomVersion/37/CustomVersion.cps         |   8 ++
 .../cps/CustomVersion/42/CustomVersion.cps         |   8 ++
 .../cps/CustomVersion/55/CustomVersion.cps         |   8 ++
 .../find_package-CPS/cps/sample/1.1.0/sample.cps   |   8 ++
 .../find_package-CPS/cps/sample/1.2.3/sample.cps   |   8 ++
 .../find_package-CPS/cps/sample/1.4.2/sample.cps   |   8 ++
 .../find_package-CPS/cps/sample/1.5.0/sample.cps   |   7 ++
 .../find_package-CPS/cps/transitiveversion.cps     |  11 ++
 34 files changed, 449 insertions(+), 43 deletions(-)
 create mode 100644 Tests/FindPackageCpsTest/share/cps/SortLib/SortLib.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/CompatVersion.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/CustomVersion.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/ExactVersion.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/MissingVersion1-result.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/MissingVersion1-stderr.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/MissingVersion1.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/MissingVersion2-result.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/MissingVersion2-stderr.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/MissingVersion2.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/MultipleVersions.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/TransitiveVersion.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit1.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit2.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit3-result.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit3-stderr.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit3.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit4-result.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit4-stderr.txt
 create mode 100644 Tests/RunCMake/find_package-CPS/VersionLimit4.cmake
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/CustomVersion/37/CustomVersion.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/CustomVersion/42/CustomVersion.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/CustomVersion/55/CustomVersion.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/sample/1.1.0/sample.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/sample/1.2.3/sample.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/sample/1.4.2/sample.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/sample/1.5.0/sample.cps
 create mode 100644 Tests/RunCMake/find_package-CPS/cps/transitiveversion.cps

diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 1b6a555..cae7150 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -79,18 +79,14 @@ The command has a few modes by which it searches for packages:
   version files are used).
 
   .. note::
-
     If the experimental ``CMAKE_EXPERIMENTAL_FIND_CPS_PACKAGES`` is enabled,
     files named ``<PackageName>.cps`` and ``<lowercasePackageName>.cps`` are
     also considered.  These files provide package information according to the
     |CPS|_ (CPS), which is more portable than CMake script.  Aside from any
     explicitly noted exceptions, any references to "config files", "config
     mode", "package configuration files", and so forth refer equally to both
-    CPS and CMake-script files.  However, some features of ``find_package``
-    are not supported at this time when a CPS file is found.  In particular,
-    if a ``VERSION`` requirement is specified, only ``.cps`` files which do not
-    provide version information will be rejected.  (We expect to implement
-    proper version validation in the near future.)
+    CPS and CMake-script files.  This functionality is a work in progress, and
+    some features may be missing.
 
     Search is implemented in a manner that will tend to prefer |CPS| files
     over CMake-script config files in most cases.  Specifying ``CONFIGS``
@@ -211,15 +207,20 @@ specified:
 * A single version with the format ``major[.minor[.patch[.tweak]]]``, where
   each component is a numeric value.
 * A version range with the format ``versionMin...[<]versionMax`` where
-  ``versionMin`` and ``versionMax`` have the same format and constraints
-  on components being integers as the single version.  By default, both end
-  points are included.  By specifying ``<``, the upper end point will be
-  excluded. Version ranges are only supported with CMake 3.19 or later.
-  Note that it is not possible to extend the compatibility range specified
-  by the package's version file.  For example, if the package version file
-  specifies compatibility within a minor version, it is not possible to
-  extend the compatibility to several minor versions by specifying a
-  version range.
+  ``versionMin`` and ``versionMax`` have the same format and constraints on
+  components being integers as the single version.  By default, both end points
+  are included.  By specifying ``<``, the upper end point will be excluded.
+  Version ranges are only supported with CMake 3.19 or later.
+
+.. note::
+  With the exception of CPS packages, version support is currently provided
+  only on a package-by-package basis.  When a version range is specified but
+  the package is only designed to expect a single version, the package will
+  ignore the upper end point of the range and only take the single version at
+  the lower end of the range into account.  Non-CPS packages that do support
+  version ranges do so in a manner that is determined by the individual
+  package.  See the `Version Selection`_ section below for details and
+  important caveats.
 
 The ``EXACT`` option requests that the version be matched exactly. This option
 is incompatible with the specification of a version range.
@@ -227,11 +228,7 @@ is incompatible with the specification of a version range.
 If no ``[version]`` and/or component list is given to a recursive invocation
 inside a find-module, the corresponding arguments are forwarded
 automatically from the outer call (including the ``EXACT`` flag for
-``[version]``).  Version support is currently provided only on a
-package-by-package basis (see the `Version Selection`_ section below).
-When a version range is specified but the package is only designed to expect
-a single version, the package will ignore the upper end point of the range and
-only take the single version at the lower end of the range into account.
+``[version]``).
 
 See the :command:`cmake_policy` command documentation for discussion
 of the ``NO_POLICY_SCOPE`` option.
@@ -749,7 +746,7 @@ sets these variables:
 These variables are checked by the ``find_package`` command to determine
 whether the configuration file provides an acceptable version.  They
 are not available after the ``find_package`` call returns.  If the version
-is acceptable the following variables are set:
+is acceptable, the following variables are set:
 
 ``<PackageName>_VERSION``
   Full provided version string
@@ -766,12 +763,80 @@ is acceptable the following variables are set:
 
 and the corresponding package configuration file is loaded.
 
+.. note::
+  While the exact behavior of version matching is determined by the individual
+  package, many packages use :command:`write_basic_package_version_file` to
+  supply this logic.  The version check scripts this produces have some notable
+  caveats with respect to version ranges:
+
+  * The upper end of a version range acts as a hard limit on what versions will
+    be accepted.  Thus, while a request for version ``1.4.0`` might be
+    satisfied by a package whose version is ``1.6.0`` and which advertises
+    'same major version' compatibility, the same package will be rejected if
+    the requested version range is ``1.4.0...1.5.0``.
+
+  * Both ends of the version range must match the package's advertised
+    compatibility level. For example, if a package advertises 'same major and
+    minor version' compatibility, requesting the version range
+    ``1.4.0...<1.5.5`` or ``1.4.0...1.5.0`` will result in that package being
+    rejected, even if the package version is ``1.4.1``.
+
+  As a result, it is not possible to use a version range to extend the range
+  of compatible package versions that will be accepted.
+
 |CPS|
 """""
 
-For |CPS| package configuration files, no version checking is performed at
-this time.  However, packages using the ``simple`` version schema will set
-the following variables:
+For |CPS| package configuration files, package version numbers are checked by
+CMake according to the set of recognized version schemas. At present, the
+following schemas are recognized:
+
+  ``simple``
+    Version numbers are a tuple of integers followed by an optional trailing
+    segment which is ignored with respect to version comparisons.
+
+  ``custom``
+    The mechanism for interpreting version numbers is unspecified.  The version
+    strings must match exactly for the package to be accepted.
+
+Refer to |cps-version_schema|_ for a more detailed explanation of each schema
+and how comparisons for each are performed.  Note that the specification may
+include schemas that are not supported by CMake.
+
+In addition to the package's ``version``, CPS allows packages to optionally
+specify a |cps-compat_version|_, which is the oldest version for which the
+package provides compatibility.  That is, the package warrants that a consumer
+expecting the ``compat_version`` should be able to use the package, even if the
+package's actual version is newer.  If not specified, the ``compat_version``
+is implicitly equal to the package version, i.e. no backwards compatibility is
+provided.
+
+When a package uses a recognized schema, CMake will determine the package's
+acceptability according to the following rules:
+
+* If ``EXACT`` was specified, or if the package does not supply a
+  ``compat_version``, the package's ``version`` must equal the requested
+  version.
+
+* Otherwise:
+
+  * The package's ``version`` must be greater than or equal to the requested
+    (minimum) version, and
+
+  * the package's ``compat_version`` must be less than or equal to the
+    requested (minimum) version, and
+
+  * if a requested maximum version was given, it must be greater than (or equal
+    to, depending on whether the maximum version is specified as inclusive or
+    exclusive) the package's ``version``.
+
+.. note::
+  This implementation of range matching was chosen in order to most closely
+  match the behavior of :command:`write_basic_package_version_file`, albeit
+  without the case where an overly broad range matches nothing.
+
+For packages using the ``simple`` version schema, if the version is acceptable,
+the following variables are set:
 
 ``<PackageName>_VERSION``
   Full provided version string
@@ -878,3 +943,9 @@ requirements are not satisfied.
 
 .. _CPS: https://cps-org.github.io/cps/
 .. |CPS| replace:: Common Package Specification
+
+.. _cps-compat_version: https://cps-org.github.io/cps/schema.html#compat-version
+.. |cps-compat_version| replace:: ``compat_version``
+
+.. _cps-version_schema: https://cps-org.github.io/cps/schema.html#version-schema
+.. |cps-version_schema| replace:: ``version_schema``
diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index 993fa93..48d33eb 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -59,6 +59,7 @@
 namespace {
 
 using pdt = cmFindPackageCommand::PackageDescriptionType;
+using ParsedVersion = cmPackageInfoReader::Pep440Version;
 
 template <template <typename> class Op>
 struct StrverscmpOp
@@ -2717,15 +2718,61 @@ bool cmFindPackageCommand::CheckVersion(std::string const& config_file)
     std::unique_ptr<cmPackageInfoReader> reader =
       cmPackageInfoReader::Read(config_file);
     if (reader && reader->GetName() == this->Name) {
+      // Read version information.
       cm::optional<std::string> cpsVersion = reader->GetVersion();
+      cm::optional<ParsedVersion> const& parsedVersion =
+        reader->ParseVersion(cpsVersion);
       bool const hasVersion = cpsVersion.has_value();
 
+      // Test for version compatibility.
+      result = this->Version.empty();
       if (hasVersion) {
         version = std::move(*cpsVersion);
-        // TODO: Implement version check for CPS
-        result = true;
-      } else {
-        result = this->Version.empty();
+
+        if (!this->Version.empty()) {
+          if (!parsedVersion) {
+            // If we don't understand the version, compare the exact versions
+            // using full string comparison. This is the correct behavior for
+            // the "custom" schema, and the best we can do otherwise.
+            result = (this->Version == version);
+          } else if (this->VersionExact) {
+            // If EXACT is specified, the version must be exactly the requested
+            // version.
+            result =
+              cmSystemTools::VersionCompareEqual(this->Version, version);
+          } else {
+            // Do we have a compat_version?
+            cm::optional<std::string> const& compatVersion =
+              reader->GetCompatVersion();
+            if (reader->ParseVersion(compatVersion)) {
+              // If yes, the initial result is whether the requested version is
+              // between the actual version and the compat version, inclusive.
+              result = cmSystemTools::VersionCompareGreaterEq(version,
+                                                              this->Version) &&
+                cmSystemTools::VersionCompareGreaterEq(this->Version,
+                                                       *compatVersion);
+
+              if (result && !this->VersionMax.empty()) {
+                // We must also check that the version is less than the version
+                // limit.
+                if (this->VersionRangeMax == VERSION_ENDPOINT_EXCLUDED) {
+                  result = cmSystemTools::VersionCompareGreater(
+                    this->VersionMax, version);
+                } else {
+                  result = cmSystemTools::VersionCompareGreaterEq(
+                    this->VersionMax, version);
+                }
+              }
+            } else {
+              // If no, compat_version is assumed to be exactly the actual
+              // version, so the result is whether the requested version is
+              // exactly the actual version, and we can ignore the version
+              // limit.
+              result =
+                cmSystemTools::VersionCompareEqual(this->Version, version);
+            }
+          }
+        }
       }
 
       if (result) {
@@ -2758,8 +2805,6 @@ bool cmFindPackageCommand::CheckVersion(std::string const& config_file)
         if (result && hasVersion) {
           this->VersionFound = version;
 
-          cm::optional<cmPackageInfoReader::Pep440Version> const&
-            parsedVersion = reader->ParseVersion();
           if (parsedVersion) {
             std::vector<unsigned> const& versionParts =
               parsedVersion->ReleaseComponents;
diff --git a/Source/cmPackageInfoReader.cxx b/Source/cmPackageInfoReader.cxx
index dd03943..a556ab8 100644
--- a/Source/cmPackageInfoReader.cxx
+++ b/Source/cmPackageInfoReader.cxx
@@ -484,11 +484,20 @@ cm::optional<std::string> cmPackageInfoReader::GetVersion() const
   return cm::nullopt;
 }
 
+cm::optional<std::string> cmPackageInfoReader::GetCompatVersion() const
+{
+  Json::Value const& version = this->Data["compat_version"];
+  if (version.isString()) {
+    return version.asString();
+  }
+  return cm::nullopt;
+}
+
 cm::optional<cmPackageInfoReader::Pep440Version>
-cmPackageInfoReader::ParseVersion() const
+cmPackageInfoReader::ParseVersion(
+  cm::optional<std::string> const& version) const
 {
   // Check that we have a version.
-  cm::optional<std::string> const& version = this->GetVersion();
   if (!version) {
     return cm::nullopt;
   }
diff --git a/Source/cmPackageInfoReader.h b/Source/cmPackageInfoReader.h
index 509a72e..26eb807 100644
--- a/Source/cmPackageInfoReader.h
+++ b/Source/cmPackageInfoReader.h
@@ -43,6 +43,7 @@ public:
 
   std::string GetName() const;
   cm::optional<std::string> GetVersion() const;
+  cm::optional<std::string> GetCompatVersion() const;
 
   // NOTE: The eventual intent is for CPS to support multiple version schemas,
   // and in particular, we expect to want to support "simple", "custom", "rpm",
@@ -65,10 +66,11 @@ public:
   // FIXME: Return a sum type (e.g. {cm,std}::variant) of possible versions
   // when we support more than just the "simple" (and possibly "pep440")
   // schema(s).
-  /// If the package uses the 'simple' version scheme, obtain the version as
-  /// a numeric tuple and optional trailing string.  Returns a disengaged
-  /// optional for other schemes or if no version is specified.
-  cm::optional<Pep440Version> ParseVersion() const;
+  /// If the package uses the 'simple' version scheme, parse the provided
+  /// version string as a numeric tuple and optional trailing string.  Returns
+  /// a disengaged optional for other schemes or if no version is specified.
+  cm::optional<Pep440Version> ParseVersion(
+    cm::optional<std::string> const& version) const;
 
   std::vector<cmPackageRequirement> GetRequirements() const;
   std::vector<std::string> GetComponentNames() const;
diff --git a/Tests/FindPackageCpsTest/CMakeLists.txt b/Tests/FindPackageCpsTest/CMakeLists.txt
index dfb59e8..73b76da 100644
--- a/Tests/FindPackageCpsTest/CMakeLists.txt
+++ b/Tests/FindPackageCpsTest/CMakeLists.txt
@@ -91,13 +91,12 @@ endif()
 set(SortLib_DIR "" CACHE FILEPATH "Wipe out find results for testing." FORCE)
 unset(SortLib_VERSION)
 
-# TODO Add this test once CPS version checking is implemented.
-# set(SortLib_DIR "" CACHE FILEPATH "Wipe out find results for testing." FORCE)
-# FIND_PACKAGE(SortLib 4.0 CONFIG)
-# IF (NOT "${SortLib_VERSION}" STREQUAL "4.0.0")
-#   message(SEND_ERROR "FIND_PACKAGE_SORT_ORDER gave up too soon! ${SortLib_VERSION}")
-# endif()
-# unset(SortLib_VERSION)
+set(SortLib_DIR "" CACHE FILEPATH "Wipe out find results for testing." FORCE)
+FIND_PACKAGE(SortLib 4.0 CONFIG)
+IF (NOT "${SortLib_VERSION}" STREQUAL "4.0.0")
+  message(SEND_ERROR "FIND_PACKAGE_SORT_ORDER gave up too soon! ${SortLib_VERSION}")
+endif()
+unset(SortLib_VERSION)
 
 set(SortFramework_DIR "" CACHE FILEPATH "Wipe out find results for testing." FORCE)
 set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
diff --git a/Tests/FindPackageCpsTest/share/cps/SortLib/SortLib.cps b/Tests/FindPackageCpsTest/share/cps/SortLib/SortLib.cps
new file mode 100644
index 0000000..fdc99dc
--- /dev/null
+++ b/Tests/FindPackageCpsTest/share/cps/SortLib/SortLib.cps
@@ -0,0 +1,7 @@
+{
+  "cps_version": "0.13",
+  "name": "SortLib",
+  "version": "4.0.0",
+  "cps_path": "@prefix@/cps/SortLib",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/CompatVersion.cmake b/Tests/RunCMake/find_package-CPS/CompatVersion.cmake
new file mode 100644
index 0000000..a8a26e1
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/CompatVersion.cmake
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package that is version-compatible with our request.
+find_package(Sample 1.2.0 REQUIRED)
+if(NOT Sample_VERSION STREQUAL "1.2.3+clarke")
+  message(SEND_ERROR "Sample wrong version ${Sample_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/CustomVersion.cmake b/Tests/RunCMake/find_package-CPS/CustomVersion.cmake
new file mode 100644
index 0000000..5ec5f85
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/CustomVersion.cmake
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION ASC)
+
+###############################################################################
+# Test finding a package that uses the "custom" version schema.
+find_package(CustomVersion 42 REQUIRED)
+if(NOT CustomVersion_VERSION EQUAL 42)
+  message(SEND_ERROR "CustomVersion wrong version ${CustomVersion_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/ExactVersion.cmake b/Tests/RunCMake/find_package-CPS/ExactVersion.cmake
new file mode 100644
index 0000000..6fbf614
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/ExactVersion.cmake
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with multiple suitable versions (exact match).
+find_package(Sample 1.1.0 EXACT REQUIRED)
+if(NOT Sample_VERSION STREQUAL "1.1.0+asimov")
+  message(SEND_ERROR "Sample wrong version ${Sample_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/MissingVersion1-result.txt b/Tests/RunCMake/find_package-CPS/MissingVersion1-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MissingVersion1-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/find_package-CPS/MissingVersion1-stderr.txt b/Tests/RunCMake/find_package-CPS/MissingVersion1-stderr.txt
new file mode 100644
index 0000000..76879a2
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MissingVersion1-stderr.txt
@@ -0,0 +1,13 @@
+CMake Error at MissingVersion1\.cmake:[0-9]+ \(find_package\):
+  Could not find a configuration file for package "Sample" that is compatible
+  with requested version "1\.2\.7"\.
+
+  The following configuration files were considered but not accepted:
+
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.5\.0/sample\.cps, version: 1\.5\.0\+niven
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.4\.2/sample\.cps, version: 1\.4\.2\+adams
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.2\.3/sample\.cps, version: 1\.2\.3\+clarke
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.1\.0/sample\.cps, version: 1\.1\.0\+asimov
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:3 \(include\)
diff --git a/Tests/RunCMake/find_package-CPS/MissingVersion1.cmake b/Tests/RunCMake/find_package-CPS/MissingVersion1.cmake
new file mode 100644
index 0000000..1a01bb9
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MissingVersion1.cmake
@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with no suitable version matches.
+find_package(Sample 1.2.7 REQUIRED)
diff --git a/Tests/RunCMake/find_package-CPS/MissingVersion2-result.txt b/Tests/RunCMake/find_package-CPS/MissingVersion2-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MissingVersion2-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/find_package-CPS/MissingVersion2-stderr.txt b/Tests/RunCMake/find_package-CPS/MissingVersion2-stderr.txt
new file mode 100644
index 0000000..c984ce7
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MissingVersion2-stderr.txt
@@ -0,0 +1,13 @@
+CMake Error at MissingVersion2\.cmake:[0-9]+ \(find_package\):
+  Could not find a configuration file for package "Sample" that is compatible
+  with requested version "1\.4\.9"\.
+
+  The following configuration files were considered but not accepted:
+
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.5\.0/sample\.cps, version: 1\.5\.0\+niven
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.4\.2/sample\.cps, version: 1\.4\.2\+adams
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.2\.3/sample\.cps, version: 1\.2\.3\+clarke
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.1\.0/sample\.cps, version: 1\.1\.0\+asimov
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:3 \(include\)
diff --git a/Tests/RunCMake/find_package-CPS/MissingVersion2.cmake b/Tests/RunCMake/find_package-CPS/MissingVersion2.cmake
new file mode 100644
index 0000000..2e8e737
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MissingVersion2.cmake
@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with no suitable version matches.
+find_package(Sample 1.4.9 REQUIRED)
diff --git a/Tests/RunCMake/find_package-CPS/MultipleVersions.cmake b/Tests/RunCMake/find_package-CPS/MultipleVersions.cmake
new file mode 100644
index 0000000..6fe1691
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/MultipleVersions.cmake
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with multiple suitable versions (permissive match).
+find_package(Sample 1.1.0 REQUIRED)
+if(NOT Sample_VERSION STREQUAL "1.2.3+clarke")
+  message(SEND_ERROR "Sample wrong version ${Sample_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/RunCMakeTest.cmake b/Tests/RunCMake/find_package-CPS/RunCMakeTest.cmake
index 67de955..8df4f60 100644
--- a/Tests/RunCMake/find_package-CPS/RunCMakeTest.cmake
+++ b/Tests/RunCMake/find_package-CPS/RunCMakeTest.cmake
@@ -8,6 +8,22 @@ set(RunCMake_TEST_OPTIONS
   "-DCMAKE_EXPERIMENTAL_FIND_CPS_PACKAGES:STRING=e82e467b-f997-4464-8ace-b00808fff261"
   )
 
+# Version-matching tests
+run_cmake(ExactVersion)
+run_cmake(CompatVersion)
+run_cmake(MultipleVersions)
+run_cmake(VersionLimit1)
+run_cmake(VersionLimit2)
+run_cmake(TransitiveVersion)
+run_cmake(CustomVersion)
+
+# Version-matching failure tests
+run_cmake(MissingVersion1)
+run_cmake(MissingVersion2)
+run_cmake(VersionLimit3)
+run_cmake(VersionLimit4)
+
+# Component-related failure tests
 run_cmake(MissingTransitiveDependency)
 run_cmake(MissingComponent)
 run_cmake(MissingComponentDependency)
diff --git a/Tests/RunCMake/find_package-CPS/TransitiveVersion.cmake b/Tests/RunCMake/find_package-CPS/TransitiveVersion.cmake
new file mode 100644
index 0000000..d4172ab
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/TransitiveVersion.cmake
@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION ASC)
+
+###############################################################################
+# Test finding a package with a versioned dependency.
+find_package(TransitiveVersion REQUIRED)
+if(NOT Sample_VERSION STREQUAL "1.2.3+clarke")
+  message(SEND_ERROR "Sample wrong version ${Sample_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit1.cmake b/Tests/RunCMake/find_package-CPS/VersionLimit1.cmake
new file mode 100644
index 0000000..877746d
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit1.cmake
@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with multiple suitable versions when a version limit
+# is present but not restricting the matches.
+find_package(Sample 1.1.0...1.2.5 REQUIRED)
+if(NOT Sample_VERSION STREQUAL "1.2.3+clarke")
+  message(SEND_ERROR "Sample wrong version ${Sample_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit2.cmake b/Tests/RunCMake/find_package-CPS/VersionLimit2.cmake
new file mode 100644
index 0000000..3d614b4
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit2.cmake
@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with multiple suitable versions when a version limit
+# is present and restricting the matches.
+find_package(Sample 1.1.0...<1.2.0 REQUIRED)
+if(NOT Sample_VERSION STREQUAL "1.1.0+asimov")
+  message(SEND_ERROR "Sample wrong version ${Sample_VERSION} !")
+endif()
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit3-result.txt b/Tests/RunCMake/find_package-CPS/VersionLimit3-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit3-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit3-stderr.txt b/Tests/RunCMake/find_package-CPS/VersionLimit3-stderr.txt
new file mode 100644
index 0000000..3b1c5ef
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit3-stderr.txt
@@ -0,0 +1,13 @@
+CMake Error at VersionLimit3\.cmake:[0-9]+ \(find_package\):
+  Could not find a configuration file for package "Sample" that is compatible
+  with requested version range "1\.2\.0\.\.\.1\.2\.2"\.
+
+  The following configuration files were considered but not accepted:
+
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.5\.0/sample\.cps, version: 1\.5\.0\+niven
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.4\.2/sample\.cps, version: 1\.4\.2\+adams
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.2\.3/sample\.cps, version: 1\.2\.3\+clarke
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.1\.0/sample\.cps, version: 1\.1\.0\+asimov
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:3 \(include\)
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit3.cmake b/Tests/RunCMake/find_package-CPS/VersionLimit3.cmake
new file mode 100644
index 0000000..a7101f2
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit3.cmake
@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with multiple suitable versions when a version limit
+# is excluding a match.
+find_package(Sample 1.2.0...1.2.2 REQUIRED)
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit4-result.txt b/Tests/RunCMake/find_package-CPS/VersionLimit4-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit4-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit4-stderr.txt b/Tests/RunCMake/find_package-CPS/VersionLimit4-stderr.txt
new file mode 100644
index 0000000..67cef15
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit4-stderr.txt
@@ -0,0 +1,13 @@
+CMake Error at VersionLimit4\.cmake:[0-9]+ \(find_package\):
+  Could not find a configuration file for package "Sample" that is compatible
+  with requested version range "1\.2\.0\.\.\.<1\.2\.3"\.
+
+  The following configuration files were considered but not accepted:
+
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.5\.0/sample\.cps, version: 1\.5\.0\+niven
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.4\.2/sample\.cps, version: 1\.4\.2\+adams
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.2\.3/sample\.cps, version: 1\.2\.3\+clarke
+    .*/Tests/RunCMake/find_package-CPS/cps/sample/1\.1\.0/sample\.cps, version: 1\.1\.0\+asimov
+
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:3 \(include\)
diff --git a/Tests/RunCMake/find_package-CPS/VersionLimit4.cmake b/Tests/RunCMake/find_package-CPS/VersionLimit4.cmake
new file mode 100644
index 0000000..ade7bfb
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/VersionLimit4.cmake
@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 4.0)
+
+include(Setup.cmake)
+
+set(CMAKE_FIND_PACKAGE_SORT_ORDER NAME)
+set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+###############################################################################
+# Test finding a package with multiple suitable versions when a version limit
+# is excluding a match.
+find_package(Sample 1.2.0...<1.2.3 REQUIRED)
diff --git a/Tests/RunCMake/find_package-CPS/cps/CustomVersion/37/CustomVersion.cps b/Tests/RunCMake/find_package-CPS/cps/CustomVersion/37/CustomVersion.cps
new file mode 100644
index 0000000..805694b
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/CustomVersion/37/CustomVersion.cps
@@ -0,0 +1,8 @@
+{
+  "cps_version": "0.13",
+  "name": "CustomVersion",
+  "version": "37",
+  "version_schema": "custom",
+  "cps_path": "@prefix@/cps/CustomVersion/37",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/CustomVersion/42/CustomVersion.cps b/Tests/RunCMake/find_package-CPS/cps/CustomVersion/42/CustomVersion.cps
new file mode 100644
index 0000000..973900e
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/CustomVersion/42/CustomVersion.cps
@@ -0,0 +1,8 @@
+{
+  "cps_version": "0.13",
+  "name": "CustomVersion",
+  "version": "42",
+  "version_schema": "custom",
+  "cps_path": "@prefix@/cps/CustomVersion/42",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/CustomVersion/55/CustomVersion.cps b/Tests/RunCMake/find_package-CPS/cps/CustomVersion/55/CustomVersion.cps
new file mode 100644
index 0000000..23226ac
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/CustomVersion/55/CustomVersion.cps
@@ -0,0 +1,8 @@
+{
+  "cps_version": "0.13",
+  "name": "CustomVersion",
+  "version": "55",
+  "version_schema": "custom",
+  "cps_path": "@prefix@/cps/CustomVersion/55",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/sample/1.1.0/sample.cps b/Tests/RunCMake/find_package-CPS/cps/sample/1.1.0/sample.cps
new file mode 100644
index 0000000..5716b9b
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/sample/1.1.0/sample.cps
@@ -0,0 +1,8 @@
+{
+  "cps_version": "0.13",
+  "name": "Sample",
+  "version": "1.1.0+asimov",
+  "compat_version": "1.0.0",
+  "cps_path": "@prefix@/cps/sample/1.1.0",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/sample/1.2.3/sample.cps b/Tests/RunCMake/find_package-CPS/cps/sample/1.2.3/sample.cps
new file mode 100644
index 0000000..e748528
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/sample/1.2.3/sample.cps
@@ -0,0 +1,8 @@
+{
+  "cps_version": "0.13",
+  "name": "Sample",
+  "version": "1.2.3+clarke",
+  "compat_version": "1.0.0",
+  "cps_path": "@prefix@/cps/sample/1.2.3",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/sample/1.4.2/sample.cps b/Tests/RunCMake/find_package-CPS/cps/sample/1.4.2/sample.cps
new file mode 100644
index 0000000..8b017bc
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/sample/1.4.2/sample.cps
@@ -0,0 +1,8 @@
+{
+  "cps_version": "0.13",
+  "name": "Sample",
+  "version": "1.4.2+adams",
+  "compat_version": "1.3.0",
+  "cps_path": "@prefix@/cps/sample/1.4.2",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/sample/1.5.0/sample.cps b/Tests/RunCMake/find_package-CPS/cps/sample/1.5.0/sample.cps
new file mode 100644
index 0000000..bf9a375
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/sample/1.5.0/sample.cps
@@ -0,0 +1,7 @@
+{
+  "cps_version": "0.13",
+  "name": "Sample",
+  "version": "1.5.0+niven",
+  "cps_path": "@prefix@/cps/sample/1.5.0",
+  "components": {}
+}
diff --git a/Tests/RunCMake/find_package-CPS/cps/transitiveversion.cps b/Tests/RunCMake/find_package-CPS/cps/transitiveversion.cps
new file mode 100644
index 0000000..71b2f03
--- /dev/null
+++ b/Tests/RunCMake/find_package-CPS/cps/transitiveversion.cps
@@ -0,0 +1,11 @@
+{
+  "cps_version": "0.13",
+  "name": "TransitiveVersion",
+  "cps_path": "@prefix@/cps",
+  "requires": {
+    "Sample": {
+      "version": "1.2.0"
+    }
+  },
+  "components": {}
+}
-- 
cgit v0.12