refactor(compilation): migrate ccache to extension; remove legacy ccache.sh

Wires the new ccache extension (extensions/ccache.sh) into the
compilation pipeline, replacing the in-core lib/functions/compilation/
ccache.sh module that was sourced unconditionally.

Changes:
  - lib/functions/compilation/kernel.sh, uboot.sh: wrap the compile
    pass with do_with_compile_wrapper so the new compile_wrapper_pre/
    _post hooks fire around it.
  - lib/functions/configuration/compilation-config.sh: dispatch
    compile_prepare_vars (early phase, before any make-quoted-params
    array is built) instead of inlining configure-ccache. Also clears
    stale CCACHE export from a previous artifact iteration so a
    second uboot/kernel call in the same shell can't reuse a now-
    disabled cache. Keeps a one-shot deprecation warning if any
    user-patch still sources the legacy lib.config.
  - lib/functions/configuration/main-config.sh: if USE_CCACHE=yes
    (or the ccache-remote extension is enabled) auto-enable the
    'ccache' extension before initialize_extension_manager runs.
    Honours both EXT alias and the legacy space-separated
    ENABLE_EXTENSIONS form.
  - lib/functions/general/extensions.sh: extract
    extension_list_normalized helper used by the auto-enable shim.
  - lib/functions/compilation/ccache.sh: removed (logic moved to
    extensions/ccache.sh).

Behaviour is preserved for USE_CCACHE=yes (default-on for kernel/uboot
builds) and USE_CCACHE=no callers. ENABLE_EXTENSIONS=ccache-remote
implicitly pulls in ccache, matching pre-refactor coupling.

Assisted-by: Claude:claude-opus-4.7

Author: iav

lib/functions/compilation/ccache.sh

@@ -256,11 +256,11 @@ function kernel_build() {
 	cd "${kernel_work_dir}" || exit_with_error "Can't cd to kernel_work_dir: ${kernel_work_dir}"
 
 	display_alert "Building kernel" "${LINUXFAMILY} ${LINUXCONFIG} ${build_targets_build[*]}" "info"
-	do_with_ccache_statistics \
+	do_with_compile_wrapper \
 		run_kernel_make_long_running "${install_make_params_quoted[@]@Q}" "${build_targets_build[@]}" # "V=1" # "-s" silent mode, "V=1" verbose mode
 
 	display_alert "Installing kernel" "${LINUXFAMILY} ${LINUXCONFIG} ${build_targets_install[*]}" "info"
-	do_with_ccache_statistics \
+	do_with_compile_wrapper \
 		run_kernel_make_long_running "${install_make_params_quoted[@]@Q}" "${build_targets_install[@]}" # "V=1" # "-s" silent mode, "V=1" verbose mode
 
 	display_alert "Kernel built in" "$((SECONDS - ts)) seconds - ${version}-${LINUXFAMILY}" "info"

lib/functions/compilation/kernel.sh

@@ -270,7 +270,7 @@ function compile_uboot_target() {
 
 	display_alert "${uboot_prefix}Compiling u-boot" "${version} ${target_make} with gcc '${gcc_version_main}'" "info"
 	declare -g if_error_detail_message="${uboot_prefix}Failed to build u-boot ${version} ${target_make}"
-	do_with_ccache_statistics run_host_command_logged_long_running \
+	do_with_compile_wrapper run_host_command_logged_long_running \
 		"env" "-i" "${uboot_make_envs[@]}" \
 		pipetty make "$target_make" "$CTHREADS" "${cross_compile}"
 

lib/functions/compilation/uboot.sh

@@ -8,22 +8,38 @@
 # https://github.com/armbian/build/
 
 function prepare_compilation_vars() {
-	#  moved from config: rpardini: ccache belongs in compilation, not config. I think.
-	if [[ $USE_CCACHE == yes || ${PRIVATE_CCACHE} == yes ]]; then
-		display_alert "using CCACHE" "USE_CCACHE or PRIVATE_CCACHE is set to yes" "warn"
-
-		CCACHE=ccache
-		export PATH="/usr/lib/ccache:$PATH" # this actually needs export'ing
-		# private ccache directory to avoid permission issues when using build script with "sudo"
-		# see https://ccache.samba.org/manual.html#_sharing_a_cache for alternative solution
-		[[ $PRIVATE_CCACHE == yes ]] && export CCACHE_DIR=$SRC/cache/ccache # actual export
-
-		# Set default umask for ccache to allow write access for all users (enables cache sharing)
-		# CCACHE_UMASK=000 creates files with permissions 666 (rw-rw-rw-) and dirs with 777 (rwxrwxrwx)
-		# Only set this for shared cache, not for private cache
-		[[ -z "${CCACHE_UMASK}" && "${PRIVATE_CCACHE}" != "yes" ]] && export CCACHE_UMASK=000
-	else
-		CCACHE=""
+	# Backend-agnostic dispatch point for compile-cache extensions
+	# (ccache, sccache, …). Runs after every extension_prepare_config_*
+	# (so values set late by other extensions — e.g. PRIVATE_CCACHE from
+	# ccache-remote — are visible) and before run_*_make_internal builds
+	# the env-i make arrays (so ${CCACHE} substitution and PATH prepend
+	# propagate correctly). Order-independent by construction.
+	#
+	# Reset CCACHE to empty first so a previous USE_CCACHE=yes build in
+	# the same shell (or a CCACHE exported in the user's environment)
+	# does not silently leak the wrapper into a USE_CCACHE=no run. Any
+	# enabled backend extension will assign CCACHE inside its hook.
+	declare -g CCACHE=""
+	call_extension_method "compile_prepare_vars" <<- 'COMPILE_PREPARE_VARS'
+		*compile-cache env setup hook for ccache / sccache / similar backends*
+		Called once early in default_build_start, after all extension
+		prepare_config hooks have run and before kernel/u-boot/ATF/Crust
+		make invocations begin. Implementations export the env vars their
+		backend needs (CCACHE, CCACHE_DIR, CCACHE_UMASK, SCCACHE_DIR, …)
+		so later array-building code captures them, and tweak PATH if a
+		wrapper prefix directory is needed.
+	COMPILE_PREPARE_VARS
+
+	# Framework-level limitation: USE_CCACHE / PRIVATE_CCACHE set in
+	# userpatches/lib.config (sourced after initialize_extension_manager —
+	# see main-config.sh:443 "too late to define hook functions or add
+	# extensions in lib.config") cannot auto-enable the ccache extension.
+	# Warn the user so they can migrate; we deliberately do not duplicate
+	# the env-setup logic here — it lives in extensions/ccache.sh as the
+	# sole owner of the ccache backend.
+	if [[ ("${USE_CCACHE}" == "yes" || "${PRIVATE_CCACHE}" == "yes") && -z "${CCACHE}" ]]; then
+		display_alert "USE_CCACHE / PRIVATE_CCACHE set, but no compile-cache extension is active" \
+			"likely set in userpatches/lib.config (framework limit: too late to enable extensions there). Add 'ccache' to ENABLE_EXTENSIONS / EXT in your CLI, env, or config file sourced earlier." "warn"
 	fi
 
 	# moved from config: this does not belong in configuration. it's a compilation thing.
@@ -36,7 +52,7 @@ function prepare_compilation_vars() {
 	# If CPUTHREADS is defined and a valid positive integer allow user to override CTHREADS
 	# This is useful for limiting Armbian build to a specific number of threads, e.g. for build servers
 	if [[ "$CPUTHREADS" =~ ^[1-9][0-9]*$ ]]; then
-    	CTHREADS="-j$CPUTHREADS"
+		CTHREADS="-j$CPUTHREADS"
 		echo "Using user-defined thread count: $CTHREADS"
 	fi
 

lib/functions/configuration/compilation-config.sh

@@ -47,7 +47,7 @@ function do_main_configuration() {
 		unset VENDORSUPPORT,VENDORPRIVACY,VENDORBUGS,VENDORLOGO,ROOTPWD,MAINTAINER,MAINTAINERMAIL
 	fi
 
-	[[ -z $VENDORCOLOR ]] && VENDORCOLOR="247;16;0"                           # RGB values for MOTD logo
+	[[ -z $VENDORCOLOR ]] && VENDORCOLOR="247;16;0" # RGB values for MOTD logo
 	[[ -z $VENDORURL ]] && VENDORURL="https://duckduckgo.com/"
 	[[ -z $VENDORSUPPORT ]] && VENDORSUPPORT="https://community.armbian.com/"
 	[[ -z $VENDORPRIVACY ]] && VENDORPRIVACY="https://duckduckgo.com/"
@@ -60,7 +60,7 @@ function do_main_configuration() {
 	DEST_LANG="${DEST_LANG:-"en_US.UTF-8"}"                                   # en_US.UTF-8 is default locale for target
 	display_alert "DEST_LANG..." "DEST_LANG: ${DEST_LANG}" "debug"
 
-	declare -g USE_CCACHE="${USE_CCACHE:-no}"                              # stop using ccache as our worktree is more effective
+	declare -g USE_CCACHE="${USE_CCACHE:-no}" # stop using ccache as our worktree is more effective
 
 	# Armbian config is central tool used in all builds. As its build externally, we have moved it to extension. Enable it here.
 	enable_extension "armbian-config"
@@ -173,7 +173,7 @@ function do_main_configuration() {
 
 	# Support for LUKS / cryptroot
 	if [[ $CRYPTROOT_ENABLE == yes ]]; then
-		enable_extension "fs-cryptroot-support" # add the tooling needed, cryptsetup
+		enable_extension "fs-cryptroot-support"                                   # add the tooling needed, cryptsetup
 		if [[ -z $CRYPTROOT_PASSPHRASE ]] && [[ -z $CRYPTROOT_AUTOUNLOCK ]]; then # a passphrase is mandatory if rootfs encryption is enabled, unless CRYPTROOT_AUTOUNLOCK is wanted
 			exit_with_error "Root encryption is enabled but CRYPTROOT_PASSPHRASE or CRYPTROOT_AUTOUNLOCK is not set"
 		fi
@@ -326,14 +326,48 @@ function do_main_configuration() {
 			;;
 	esac
 
-        # enable APA extension for Debian Unstable release
+	# enable APA extension for Debian Unstable release
 	# loong64 is not supported now
 	#  [ "$RELEASE" = "sid" ] && [ "$ARCH" != "loong64" ] && enable_extension "apa"
 
 	## Extensions: at this point we've sourced all the config files that will be used,
 	##             and (hopefully) not yet invoked any extension methods. So this is the perfect
 	##             place to initialize the extension manager. It will create functions
 	##             like the 'post_family_config' that is invoked below.
+
+	# Auto-enable the ccache compile-cache extension when:
+	#   - the legacy toggle is set (USE_CCACHE=yes / PRIVATE_CCACHE=yes), OR
+	#   - the ccache-remote extension is requested (it sets USE_CCACHE=yes
+	#     itself inside extension_prepare_config, too late for this
+	#     shim to react to the toggle directly, so we trigger on the
+	#     extension name instead).
+	# Skip when a competing compile-cache extension (sccache, …) is already
+	# requested. Mutex resolution lives inside the extensions themselves;
+	# the regex below just prevents redundant auto-enabling.
+	#
+	# Placed immediately before initialize_extension_manager so all
+	# in-do_main_configuration sources of USE_CCACHE / PRIVATE_CCACHE /
+	# ENABLE_EXTENSIONS are visible. The extension-list normalisation
+	# (EXT fallback + comma/whitespace handling) is shared with the
+	# per-extension mutex checks via extension_list_normalized.
+	#
+	# Note: USE_CCACHE set in userpatches/lib.config is a framework-level
+	# limitation — lib.config is sourced after initialize_extension_manager
+	# (see line ~443 'too late to define hook functions or add extensions
+	# in lib.config'). For that scenario prepare_compilation_vars emits a
+	# warning at compile phase nudging users to migrate to
+	# ENABLE_EXTENSIONS=ccache.
+	local _ext_list
+	_ext_list="$(extension_list_normalized)"
+	if [[ "${USE_CCACHE}" == "yes" ||
+		"${PRIVATE_CCACHE}" == "yes" ||
+		"${_ext_list}" == *,ccache-remote,* ]]; then
+		if [[ ! "${_ext_list}" == *,ccache,* && ! "${_ext_list}" == *,sccache,* ]]; then
+			enable_extension "ccache"
+		fi
+	fi
+	unset _ext_list
+
 	initialize_extension_manager
 
 	call_extension_method "post_family_config" "config_tweaks_post_family_config" <<- 'POST_FAMILY_CONFIG'

lib/functions/configuration/main-config.sh

@@ -24,6 +24,19 @@ function extension_hook_opt_out() {
 	fi
 }
 
+# Normalize the active extension list for substring matching.
+# Mirrors initialize_extension_manager's resolution (ENABLE_EXTENSIONS:-EXT)
+# and accepts both comma- and whitespace-separated forms. Emits a canonical
+# `,name1,name2,…,` string suitable for `[[ "$list" == *,name,* ]]` checks.
+# Stdout: the normalized list. Useful in both the in-core auto-enable shim
+# and per-extension mutex checks between mutually-exclusive extensions.
+function extension_list_normalized() {
+	local raw="${ENABLE_EXTENSIONS:-${EXT:-}}"
+	local list=",${raw// /,},"
+	while [[ "$list" == *,,* ]]; do list="${list//,,/,}"; done
+	echo "$list"
+}
+
 function extension_manager_declare_globals() {
 	# global variables managing the state of the extension manager. treat as private.
 	declare -g -A extension_function_info                # maps a function name to a string with KEY=VALUEs information about the defining extension
@@ -590,7 +603,7 @@ function enable_extensions_with_hostdeps_builtin_and_user() {
 		display_alert "Extension search" "Searching in directory: \"${ext_dir}\"" ""
 		if [[ -d "${ext_dir}" ]]; then
 			declare -a ext_list_dir=()
-			mapfile -t ext_list_dir < <(find "${ext_dir}" -maxdepth 2 -type f -name "*.sh" -print0 | xargs -0 -r grep -l "${grep_args[@]}" 2>/dev/null || true)
+			mapfile -t ext_list_dir < <(find "${ext_dir}" -maxdepth 2 -type f -name "*.sh" -print0 | xargs -0 -r grep -l "${grep_args[@]}" 2> /dev/null || true)
 			display_alert "Extension search result" "Found ${#ext_list_dir[@]} extensions in \"${ext_dir}\"" ""
 			extension_list+=("${ext_list_dir[@]}")
 		else

lib/functions/general/extensions.sh

@@ -285,9 +285,9 @@ source "${SRC}"/lib/functions/compilation/atf.sh
 #set -o nounset   ## set -u : exit the script if you try to use an uninitialised variable - one day will be enabled
 set -o errtrace # trace ERR through - enabled
 set -o errexit  ## set -e : exit the script if any statement returns a non-true return value - enabled
-### lib/functions/compilation/ccache.sh
-# shellcheck source=lib/functions/compilation/ccache.sh
-source "${SRC}"/lib/functions/compilation/ccache.sh
+### lib/functions/compilation/compile-wrapper.sh
+# shellcheck source=lib/functions/compilation/compile-wrapper.sh
+source "${SRC}"/lib/functions/compilation/compile-wrapper.sh
 
 # no errors tolerated. invoked before each sourced file to make sure.
 #set -o pipefail  # trace ERR through pipes - will be enabled "soon"