cmake: Increase cmake policy version

Increase cmake policy version from 3.12 to 4.1 in standalone builds to stop
using very old and deprecated CMake policies in standalone builds.

Also stop overriding policy version if a parent project has already set one, so
parent projects are able to control which policies are used by default based on
their own practices and needs.

In the Bitcoin Core subtree, this change causes the libmultiprocess policy
version to increase from 3.12 to 3.22, which is the version Bitcoin Core sets.

This commit only changes the policy version, it does not change the specified
minimum version of cmake required to build the project, which is 3.12.

Author: ryanofsky

CMakeLists.txt

@@ -2,7 +2,33 @@
 # Distributed under the MIT software license, see the accompanying
 # file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-cmake_minimum_required(VERSION 3.12)
+# Call cmake_minimum_required() only if it was not already called, so parent
+# projects set the policy version when this project is included via
+# add_subdirectory().
+#
+# Rationale: Different projects have different practices for choosing policy
+# versions. For example, the Bitcoin Core project sets an old policy version,
+# causing CMake to use deprecated behaviors instead of new behaviors and
+# maximize compatibility with a single old version of CMake, reducing variance
+# between builds with newer CMake versions. By contrast CMake documentation
+# recommends setting the policy version to the latest supported version of
+# CMake, as an upgrading mechanism rather than a pinning mechanism, to let
+# project authors fix problems before enabling newer policies, while not opting
+# into deprecated policies on a longer term basis.
+if(NOT DEFINED CMAKE_MINIMUM_REQUIRED_VERSION
+   OR CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 3.12)
+  # The left number in the range below is the minimum CMake version required to
+  # run this project. The right number is the CMake policy version.
+  #
+  # The purpose of the minimum version is to trigger a helpful error if a version
+  # of CMake is being used that is too old to work. If this number is changed,
+  # the version in ci/configs/olddeps.bash should be changed to match.
+  #
+  # The purpose of the policy version is to opt out of policies introduced in
+  # newer versions of CMake until they have been tested. If this number is
+  # changed, the version in ci/configs/newdeps.bash should be changed to match.
+  cmake_minimum_required(VERSION 3.12...4.1 FATAL_ERROR)
+endif()
 
 project("Libmultiprocess" CXX)
 if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)

ci/configs/newdeps.bash

@@ -2,5 +2,6 @@ CI_DESC="CI job using newest Cap'n Proto and cmake versions"
 CI_DIR=build-newdeps
 export CXXFLAGS="-Werror -Wall -Wextra -Wpedantic -Wno-unused-parameter -Wno-error=array-bounds"
 CAPNP_CHECKOUT=master
+# cmakeVersion here should match policy version in CMakeLists.txt
 NIX_ARGS=(--argstr capnprotoVersion "none" --argstr cmakeVersion "4.1.1")
 BUILD_ARGS=(-k)

ci/configs/olddeps.bash

@@ -1,5 +1,6 @@
 CI_DESC="CI job using old Cap'n Proto and cmake versions"
 CI_DIR=build-olddeps
 export CXXFLAGS="-Werror -Wall -Wextra -Wpedantic -Wno-unused-parameter -Wno-error=array-bounds"
+# cmakeVersion here should match minimum version in CMakeLists.txt
 NIX_ARGS=(--argstr capnprotoVersion "0.7.1" --argstr cmakeVersion "3.12.4")
 BUILD_ARGS=(-k)