Merge branch 'feature/add-api-compatibility-ci-job' into 'master'

ci: add API compatibility check job for merge requests

Closes IDF-8483

See merge request espressif/esp-idf!45963

.gitlab/ci/host-test.yml

@@ -53,6 +53,25 @@ check_public_headers:
         done
       done
 
+check_api_compatibility:
+  extends:
+    - .host_test_template
+    - .rules:test:host_test
+  needs:
+    - pipeline_variables
+  variables:
+    IDF_TOOLCHAIN: clang
+    INSTALL_EXTRA_TOOLS: esp-clang-libs
+  allow_failure: true
+  script:
+    - pip install "esp-api-check[gitlab] @ git+https://gitlab-ci-token:${ESPCI_TOKEN}@${GITLAB_HTTPS_HOST}/espressif/esp-api-check.git"
+    - python -m esp_api_check install-clang-bindings
+    - python -m esp_api_check gitlab
+      --gitlab-url "https://${GITLAB_HTTPS_HOST}"
+      --gitlab-token ${ESPCI_TOKEN}
+      --head-sha ${CI_MERGE_REQUEST_SOURCE_BRANCH_SHA}
+      --project-dir ${CI_PROJECT_DIR}/tools/test_apps/system/test_api_check
+
 test_nvs_coverage:
   extends:
     - .host_test_template

tools/test_apps/system/.build-test-rules.yml

@@ -159,6 +159,11 @@ tools/test_apps/system/startup:
   disable:
     - if: CONFIG_NAME == "main_task_cpu1" and IDF_TARGET not in ["esp32", "esp32s3"]
 
+tools/test_apps/system/test_api_check:
+  disable:
+    - if: IDF_TARGET == IDF_TARGET
+      reason: Not a buildable app. Used only as a CMake project by the check_api_compatibility CI job.
+
 tools/test_apps/system/test_watchpoint:
   enable:
     - if: IDF_TARGET in ["esp32", "esp32c3"] # Just one test per architecture

tools/test_apps/system/test_api_check/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.16)
+
+set(SDKCONFIG ${CMAKE_CURRENT_BINARY_DIR}/sdkconfig)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# Disabling minimal build so that "main" depends on all components in the build,
+# allowing all the public headers to be extracted.
+idf_build_set_property(MINIMAL_BUILD OFF)
+project(test_api_check)
+
+# Define __DOXYGEN__ and IDF_DOC_BUILD so that the API checker can see
+# declarations hidden behind these guards in ESP-IDF headers.
+add_compile_definitions(__DOXYGEN__ IDF_DOC_BUILD)

tools/test_apps/system/test_api_check/README.md

@@ -0,0 +1,2 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |

tools/test_apps/system/test_api_check/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+# Not setting REQUIRES so that `main.c` depends on all components in the build,
+# allowing all the public headers to be extracted.
+idf_component_register(SRCS "main.c")

tools/test_apps/system/test_api_check/sdkconfig.defaults.esp32p4

@@ -0,0 +1,3 @@
+# Clang toolchain doesn't support ESP32-P4 rev >= 3.0
+CONFIG_ESP32P4_REV_MIN_100=y
+CONFIG_ESP32P4_SELECTS_REV_LESS_V3=y