Set Minimum Policy Version for Legacy CMake Project

CMake is a widely used tool for managing the build process of projects, and over the years it has introduced many new features and policies to improve project configuration, enforce best practices, and provide more consistent behavior across platforms. However, with every new major version, some older behaviors are deprecated and eventually removed. This can cause issues when trying to build legacy projects that were created with an older version of CMake in mind.

For example, CMake 4.0 removed compatibility with versions earlier than 3.5. This means that any project that specifies a minimum required version lower than 3.5 in its CMakeLists.txt will fail to configure, even if the project itself would otherwise work fine with a modern CMake. This can be particularly frustrating when dealing with third-party projects that you do not want or cannot modify.

Consider a simple legacy project:

cmake_minimum_required(VERSION 3.4)
project(myapp)

set(CMAKE_CXX_STANDARD 17)

add_executable(${PROJECT_NAME} main.cpp)

If you try to generate build files using a modern CMake, you might encounter the following error:

CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  Compatibility with CMake < 3.5 has been removed from CMake.

  Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
  to tell CMake that the project requires at least <min> but has been updated
  to work with policies introduced by <max> or earlier.

  Or, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to try configuring anyway.

Many legacy projects actually support a higher CMake version than the cmake_minimum_required value indicates. To bypass this compatibility error, you can set the minimum policy version when configuring the project using CMAKE_POLICY_VERSION_MINIMUM variable:

cmake -S . -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5

Using this approach, you can generate build files for legacy projects without modifying their CMakeLists.txt. It's especially useful for third-party projects where you do not want to edit the source files.