Merge pull request #11452 from SunBlack/SameMajorVersion_compatibility

Switch from SameMinorVersion to SameMajorVersion compatibility

MIGRATION_GUIDE.TXT

@@ -1,3 +1,9 @@
+MIGRATION GUIDE FROM GDAL 3.10 to GDAL 3.11
+------------------------------------------
+
+- If only a specific GDAL Minor version is to be supported, this must now be
+  specified in the find_package call in CMake via a version range specification.
+
 MIGRATION GUIDE FROM GDAL 3.9 to GDAL 3.10
 ------------------------------------------
 

doc/source/development/cmake.rst

@@ -26,21 +26,30 @@ the cache variable or environment variable ``CMAKE_PREFIX_PATH``. In
 particular, CMake will consult (and set) the cache variable
 ``GDAL_DIR``.
 
-If a specific minor version is required, you can search for this via:
+If a specific minor version is at least required, you can search for this via:
 
 .. code:: cmake
 
-    find_package(GDAL 3.10 CONFIG REQUIRED)
+    find_package(GDAL 3.11 CONFIG REQUIRED)
 
-If more than one minor version is to be supported at the same time,
-``${GDAL_VERSION}`` itself must be evaluated.
+If only a single minor version should be accepted, you need to pass a version
+range to ``find_package`` (requires CMake 3.19):
 
 .. code:: cmake
 
-    find_package(GDAL CONFIG REQUIRED)
-    if(GDAL_VERSION VERSION_LESS "3.7" OR GDAL_VERSION VERSION_GREATER "3.9")
-      message(FATAL_ERROR "Required at least GDAL version 3.7 - 3.9, but found ${GDAL_VERSION}.")
-    endif()
+    find_package(GDAL 3.11.0...3.11.9 CONFIG REQUIRED)
+
+.. versionchanged:: 3.11
+   Until GDAL 3.10, GDAL has specified the same minor version as compatibility.
+   If you want older GDAL versions to be accepted, the version number must be
+   checked manually.
+
+   .. code:: cmake
+
+       find_package(GDAL CONFIG REQUIRED)
+       if(GDAL_VERSION VERSION_LESS "3.7" OR GDAL_VERSION VERSION_GREATER "3.11")
+         message(FATAL_ERROR "Required at least GDAL version 3.7 - 3.11, but found ${GDAL_VERSION}.")
+       endif()
 
 Before GDAL 3.5, it is recommended to use `find module supplied with CMake <https://cmake.org/cmake/help/latest/module/FindGDAL.html>`__.
 This also creates the ``GDAL::GDAL`` target. It requires CMake version 3.14.

gdal.cmake

@@ -575,11 +575,11 @@ if (NOT GDAL_ENABLE_MACOSX_FRAMEWORK)
   endif ()
 
   include(CMakePackageConfigHelpers)
-  # SameMinorVersion as our C++ ABI remains stable only among major.minor.XXX patch releases
+  # SameMajorVersion as the C++ ABI stability is not relevant for new linking and there are only a few breaking API changes.
   write_basic_package_version_file(
     GDALConfigVersion.cmake
     VERSION ${GDAL_VERSION}
-    COMPATIBILITY SameMinorVersion)
+    COMPATIBILITY SameMajorVersion)
   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/GDALConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/gdal/)
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/template/GDALConfig.cmake.in
                  ${CMAKE_CURRENT_BINARY_DIR}/GDALConfig.cmake @ONLY)