CMake 4.0
This is a proposed Change for Fedora Linux.
This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee.
Summary
Update CMake to version 4.0. This version breaks compatibility with projects that specify cmake_minimum_required
with only a lower bound less than 3.5
. Affected projects are tracked in this copr repo, please check if your packages are failing there.
Owner
- Name: Cristian Le
- Email: fedora@lecris.me
Detailed Description
Projects built with different major versions of CMake are generally compatible with each other due to the use of cmake_minimum_required
and CMake policies that define how the build will behave, OLD
or NEW
behavior, with the minimum version given to cmake_minimum_required
specifying that policies defined up to that version should use the NEW
behavior and policies defined from that version onward use the OLD
behavior.
Every so often a new CMake version drops support for OLD
policies, and in CMake 4.0 all policies before 3.5 are dropped (this is actually the first time the OLD
policies are being dropped). This requires various projects to check if their build will be affected by a rebuild, and adjust the CMake files accordingly.
Other changes:
- Various compatibility layers have been provided during the CMake 3.x packaging, but as the technologies improved and since CMake maintains general compatibility across major versions, these compatibility layers have become unnecessary and will be gradually removed.
- The
%cmake4*
macros are not provided and%cmake3
macros still alias the%cmake
macros. -
/usr/bin/cmake3
is no longer provided and for the time being/usr/bin/cmake4
is an additional symlink to/usr/bin/cmake
. Dropping/usr/bin/cmake4
will be raised in a future change proposal. - The
cmake.spec
file will continue to haveProvides: cmake3
, but there will NOT be aProvides: cmake4
.
- The
Migration
Compatibility with fedora releases
Any proposed changes here are compatible with any CMake versions and can be included at any point and backported to any Fedora release.
The corresponding cmake PR will not be merged until the affected packages are patched
Quick solution: Adding an environment variable or -D
option CMAKE_POLICY_VERSION_MINIMUM=3.5
would unblock the builds in 90% of the cases, but this is not ‘generally’ recommended because it is not upstream friendly, and can hide build failures if the cmake_minimum_required
is hard-coded in the files distributed in the -devel
package.
In most cases the required change is very minimal, just requiring to update all occurrences of cmake_minimum_required
e.g.
cmake_minimum_required(VERSION 3.12…4.0)
It is highly recommended to include a higher-bound which does not mean that building with any higher CMake version will break, instead if the project is built with any version in between these bounds, it will automatically use the NEW
policy. This will help in the future when needing to bump the minimum version again since it will be safe to update the minimum up to the current higher-bound.
The versions to be used are up to upstream’s discretion for which versions they want to test and support, and technically the following is also acceptable:
cmake_minimum_required(VERSION 2.8…4.0)
There may be unforeseen consequences due to the change in the policy, for example with CMP0028
change, builds can fail if the library or other target have ::
in their name. These however are generally very specialized edge-cases, so for the most parts, a simple change of cmake_minimum_required
is sufficient. Still it is best to consult with upstream’s testing infrastructure.
Benefit to Fedora
Availability of CMake 4.0 for the user to develop, and upstreaming CMake 4.0 compatibility patches.
Scope
-
Proposal owners:
- Build CMake 4.0 and impact-check affected projects
- Try to propose appropriate fixes as much as possible
- Assist the more complicated migrations and be a point of contact for upstream issue
-
Other developers:
-
Release engineering: #Releng issue number
-
Policies and guidelines: N/A (not needed for this Change)
Upgrade/compatibility impact
Affected packages would be FTBFS (in the tracked copr repo) and would require patching before the corresponding cmake PR can be merged.
How To Test
A copr repo will be provided with CMake 4.0 rebuilds. Use it to try local builds, e.g. using:
copr mock-config lecris/cmake-4.0 fedora-rawhide-x86_64
If the build is successful, that should be sufficient, but check your reverse dependencies to see if the -devel
package files are also built correctly.
Most of the policies should result in build/test failures if the package was relying on an outdated OLD
behavior, but there are some that may have more subtle behavior change. The recommendation is to forward this list to upstream for more thorough investigation:
-
CMP0054
if("var" STREQUAL "check_value")
used to be equivalent withif(var STREQUAL "check_value")
.
Dependencies
There are currently 776/2359 packages that dependent on cmake
which are affected, gathered and built using mass-pre-build in copr.
Not all build failures are due to CMake updates, and most of them would be fixed by a bump of cmake_minimum_required
.
Contingency Plan
- Contingency mechanism: N/A (no deadline set)
- Contingency deadline: No deadline necessary yet
- Blocks release? No
Documentation
- CMake 4.0 Release Notes: CMake 4.0 Release Notes — CMake 4.0.1 Documentation
- List of policies dropped: cmake-policies(7) — CMake 4.0.1 Documentation
Last edited by @x3mboy 2025-04-16T14:53:53Z
Last edited by @x3mboy 2025-04-16T14:53:53Z