From d76ddc065a7275f89fd706625c4a923f93cb69dc Mon Sep 17 00:00:00 2001
From: Frantisek Hrbata <frantisek.hrbata@espressif.com>
Date: Thu, 14 Aug 2025 10:37:38 +0200
Subject: [PATCH] feat(cmakev2/compat): add check_expected_tool_version helper

The compat.cmake file is intended to include functions necessary for
backward compatibility with cmakev1.

Add the check_expected_tool_version function, which is used by some
project_include.cmake files to verify if the tool's version matches the
installed tool. This functionality is used, for example, by esp_common.

Signed-off-by: Frantisek Hrbata <frantisek.hrbata@espressif.com>
---
 tools/cmakev2/compat.cmake | 54 ++++++++++++++++++++++++++++++++++++++
 tools/cmakev2/idf.cmake    |  1 +
 2 files changed, 55 insertions(+)
 create mode 100644 tools/cmakev2/compat.cmake

diff --git a/tools/cmakev2/compat.cmake b/tools/cmakev2/compat.cmake
new file mode 100644
index 00000000000..94fa0e1af16
--- /dev/null
+++ b/tools/cmakev2/compat.cmake
@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+include_guard(GLOBAL)
+
+#[[
+   check_expected_tool_version()
+
+   Function to verify if the tool is using the expected version and issue a
+   warning if it is not.
+#]]
+function(check_expected_tool_version tool_name tool_path)
+    set(tool_version_warning "Check Getting Started documentation or proceed at own risk.\n")
+    set(tool_version_error "Check Getting Started documentation if the error continues.\n"
+        "You can override this error and proceed with build by defining the IDF_MAINTAINER environment variable.\n")
+    set(fixing_hint "Please try to run 'idf.py fullclean' to solve it.\n")
+
+    idf_build_get_property(python PYTHON)
+    idf_build_get_property(idf_path IDF_PATH)
+
+    set(ENV{IDF_TOOLS_VERSION_HELPER} "1")
+    # Use idf_tools.py to check if tool version is supported
+    execute_process(
+        COMMAND ${python} "${idf_path}/tools/idf_tools.py"
+        "check-tool-supported" "--tool-name" "${tool_name}"
+        "--exec-path" "${tool_path}"
+        OUTPUT_VARIABLE is_version_supported
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET)
+
+    if(is_version_supported STREQUAL "False")
+        # Version is not supported. Need to get supported versions list to print them to user
+        execute_process(
+            COMMAND ${python} "${idf_path}/tools/idf_tools.py"
+            "get-tool-supported-versions" "--tool-name" "${tool_name}"
+            OUTPUT_VARIABLE tool_supported_versions
+            OUTPUT_STRIP_TRAILING_WHITESPACE
+            ERROR_QUIET)
+        # IDF maintainers can build projects with not supported versions with just a warning
+        if($ENV{IDF_MAINTAINER})
+            set(message_mode "WARNING")
+        else()
+            set(message_mode "FATAL_ERROR")
+        endif()
+
+        idf_msg(${message_mode} "\n"
+                 "Tool doesn't match supported version from list "
+                "${tool_supported_versions}: ${tool_path}\n"
+                 ${fixing_hint})
+    elseif(NOT is_version_supported STREQUAL "True")
+        idf_warn("Can not get version for tool: ${tool_path}\n" ${tool_version_warning})
+    endif()
+    unset(ENV{IDF_TOOLS_VERSION_HELPER})
+endfunction()
diff --git a/tools/cmakev2/idf.cmake b/tools/cmakev2/idf.cmake
index 794863ab16a..8128ff8f114 100644
--- a/tools/cmakev2/idf.cmake
+++ b/tools/cmakev2/idf.cmake
@@ -21,6 +21,7 @@ include(component)
 include(build)
 include(kconfig)
 include(project)
+include(compat)
 include(GetGitRevisionDescription)
 # For backward compatibility, since externalproject_add is used by
 # project_include.cmake in the bootloader component. The ExternalProject