FindBoost: Introduce CMP0093 to report Boost_VERSION in x.y.z format

This aligns module mode behaviour with config mode.

Help/manual/cmake-policies.7.rst

@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.15
 .. toctree::
    :maxdepth: 1
 
+   CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093>
    CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092>
    CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091>
    CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090>

Help/policy/CMP0093.rst

@@ -0,0 +1,24 @@
+CMP0093
+-------
+
+:module:`FindBoost` reports ``Boost_VERSION`` in ``x.y.z`` format.
+
+In CMake 3.14 and below the module would report the Boost version
+number as specified in the preprocessor definition ``BOOST_VERSION`` in
+the ``boost/version.hpp`` file. In CMake 3.15 and later it is preferred
+that the reported version number matches the ``x.y.z`` format reported
+by the CMake package shipped with Boost ``1.70.0`` and later. The macro
+value is still reported in the ``Boost_VERSION_MACRO`` variable.
+
+The ``OLD`` behavior for this policy is for :module:`FindBoost` to report
+``Boost_VERSION`` as specified in the preprocessor definition
+``BOOST_VERSION`` in ``boost/version.hpp``. The ``NEW`` behavior for this
+policy is for :module:`FindBoost` to report ``Boost_VERSION`` in
+``x.y.z`` format.
+
+This policy was introduced in CMake version 3.15.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses the ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/release/dev/FindBoost-fphsa.rst

@@ -29,3 +29,6 @@ FindBoost-fphsa
 
   * The input switch ``Boost_DETAILED_FAILURE_MSG`` was
     removed.
+
+  * ``Boost_VERSION`` now reports the version in ``x.y.z``
+    format in module mode.  See policy :policy:`CMP0093`.

Modules/FindBoost.cmake

@@ -30,9 +30,10 @@ case results are reported in variables::
   Boost_<C>_FOUND        - True if component <C> was found (<C> is upper-case)
   Boost_<C>_LIBRARY      - Libraries to link for component <C> (may include
                            target_link_libraries debug/optimized keywords)
-  Boost_VERSION          - BOOST_VERSION value from boost/version.hpp
-                           alias: Boost_VERSION_MACRO
+  Boost_VERSION_MACRO    - BOOST_VERSION value from boost/version.hpp
   Boost_VERSION_STRING   - Boost version number in x.y.z format
+  Boost_VERSION          - if CMP0093 NEW => same as Boost_VERSION_STRING
+                           if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
   Boost_LIB_VERSION      - Version string appended to library filenames
   Boost_VERSION_MAJOR    - Boost major version number (X in X.y.z)
                            alias: Boost_MAJOR_VERSION
@@ -1427,7 +1428,15 @@ if(Boost_INCLUDE_DIR)
   set(Boost_VERSION_STRING "${Boost_VERSION_MAJOR}.${Boost_VERSION_MINOR}.${Boost_VERSION_PATCH}")
 
   # Define final Boost_VERSION
-  set(Boost_VERSION ${Boost_VERSION_MACRO})
+  cmake_policy(GET CMP0093 _Boost_CMP0093
+    PARENT_SCOPE # undocumented, do not use outside of CMake
+  )
+  if("x${_Boost_CMP0093}x" STREQUAL "xNEWx")
+    set(Boost_VERSION ${Boost_VERSION_STRING})
+  else()
+    set(Boost_VERSION ${Boost_VERSION_MACRO})
+  endif()
+  unset(_Boost_CMP0093)
 
   if(Boost_DEBUG)
     message(STATUS "[ ${CMAKE_CURRENT_LIST_FILE}:${CMAKE_CURRENT_LIST_LINE} ] "

Source/cmPolicies.h

@@ -273,7 +273,9 @@ class cmMakefile;
          0, cmPolicies::WARN)                                                 \
   SELECT(POLICY, CMP0092,                                                     \
          "MSVC warning flags are not in CMAKE_<LANG>_FLAGS by default.", 3,   \
-         15, 0, cmPolicies::WARN)
+         15, 0, cmPolicies::WARN)                                             \
+  SELECT(POLICY, CMP0093, "FindBoost reports Boost_VERSION in x.y.z format.", \
+         3, 15, 0, cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \

Tests/RunCMake/FindBoost/CMP0093-NEW-stdout.txt

@@ -0,0 +1 @@
+-- Boost_VERSION=1.70.0

Tests/RunCMake/FindBoost/CMP0093-NEW.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0093 NEW)
+include(ModuleMode.cmake)

Tests/RunCMake/FindBoost/CMP0093-OLD-stdout.txt

@@ -0,0 +1 @@
+-- Boost_VERSION=107000

Tests/RunCMake/FindBoost/CMP0093-OLD.cmake

@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0093 OLD)
+include(ModuleMode.cmake)

Tests/RunCMake/FindBoost/CMP0093-UNSET-stdout.txt

@@ -0,0 +1 @@
+-- Boost_VERSION=107000

Tests/RunCMake/FindBoost/CMP0093-UNSET.cmake

@@ -0,0 +1 @@
+include(ModuleMode.cmake)

Tests/RunCMake/FindBoost/RunCMakeTest.cmake

@@ -14,3 +14,7 @@ run_cmake(ConfigModeNotFound)
 run_cmake(ModuleModeNotFound)
 unset(RunCMake-stdout-file)
 unset(RunCMake-stderr-file)
+
+run_cmake(CMP0093-NEW)
+run_cmake(CMP0093-OLD)
+run_cmake(CMP0093-UNSET)