From 0a51adb539c90e494541db44da0f26f62e10b073 Mon Sep 17 00:00:00 2001
From: Fu Hanxi <fuhanxi@espressif.com>
Date: Wed, 15 Apr 2026 13:25:02 +0200
Subject: [PATCH] ci: log per-job ccache stats

---
 .gitlab/ci/common.yml                | 19 ++++++++++++++++++-
 tools/ci/configure_ci_environment.sh | 17 ++++++++++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/.gitlab/ci/common.yml b/.gitlab/ci/common.yml
index 2d0393d7d27..0bceb92e05e 100644
--- a/.gitlab/ci/common.yml
+++ b/.gitlab/ci/common.yml
@@ -113,6 +113,11 @@ variables:
   # configure cmake related flags
   source tools/ci/configure_ci_environment.sh
 
+  if [[ "$CI_CCACHE_STATS" == 1 ]] && command -v ccache >/dev/null 2>&1 && [[ -n "$CCACHE_STATSLOG" ]]; then
+    mkdir -p "$(dirname "$CCACHE_STATSLOG")"
+    rm -f "$CCACHE_STATSLOG"
+  fi
+
   # add extra python packages
   export PYTHONPATH="$IDF_PATH/tools:$IDF_PATH/tools/esp_app_trace:$IDF_PATH/components/partition_table:$IDF_PATH/tools/ci/python_packages:$PYTHONPATH"
 
@@ -198,7 +203,19 @@ variables:
 
 .show_ccache_statistics: &show_ccache_statistics |
   # Show ccache statistics if enabled globally
-  test "$CI_CCACHE_STATS" == 1 && test -n "$(which ccache)" && ccache --show-stats || true
+  section_start "ccache_show_stats" "Show ccache statistics"
+  if [[ "$CI_CCACHE_STATS" == 1 ]] && command -v ccache >/dev/null 2>&1; then
+    if ccache --help 2>/dev/null | grep -q -- '--show-log-stats'; then
+      if [[ -n "$CCACHE_STATSLOG" && -f "$CCACHE_STATSLOG" ]]; then
+        ccache --show-log-stats -vv
+      else
+        echo "INFO: No per-job ccache statistics were recorded"
+      fi
+    else
+      ccache --show-stats -vv
+    fi
+  fi || true
+  section_end "ccache_show_stats"
 
 .upload_failed_job_log_artifacts: &upload_failed_job_log_artifacts |
   if [ $CI_JOB_STATUS = "failed" ]; then
diff --git a/tools/ci/configure_ci_environment.sh b/tools/ci/configure_ci_environment.sh
index 9c7e00a1fea..54f2e03159f 100644
--- a/tools/ci/configure_ci_environment.sh
+++ b/tools/ci/configure_ci_environment.sh
@@ -33,8 +33,23 @@ if [ "$CI_CCACHE_DISABLE" = 1 ]; then
     echo "INFO: ccache disabled globally using CI_CCACHE_DISABLE=0"
 fi
 
+# https://ccache.dev/manual/latest.html#_configuring_ccache
 # Set ccache base directory to the project checkout path, to cancel out differences between runners
-export CCACHE_BASEDIR="${CI_PROJECT_DIR}"
+export CCACHE_BASEDIR="${IDF_PATH}"
+export CCACHE_COMPILERCHECK="${CCACHE_COMPILERCHECK:-content}"
+
+# host mapping volume to share ccache fbetween runner concurrent jobs
+export CCACHE_SLOPPINESS="time_macros,file_macro,include_file_mtime,include_file_ctime"
+
+# Keep per-job statistics in the checkout directory while sharing the cache itself.
+export CCACHE_STATSLOG="${CCACHE_STATSLOG:-${IDF_PATH}/.ccache-stats.log}"
+
+# CCACHE_RECACHE Used when invalidating the current cache.
+# could be enabled by MR label "ccache:recache"
+if [ -n "${CI_MERGE_REQUEST_LABELS}" ] && echo "${CI_MERGE_REQUEST_LABELS}" | grep -q "ccache::recache"; then
+    export CCACHE_RECACHE="1"
+    echo "INFO: ccache recache enabled"
+fi
 
 # 'CI_CCACHE_DISABLE_NOHASHDIR' variable can be used at project level to revert to hash_dir=true, in
 # case we start seeing failures due to false cache hits.