refactor(compilation): extract ccache as extension (prep) + add compile_wrapper hooks

extensions/ccache.sh

@@ -0,0 +1,177 @@
+#
+# SPDX-License-Identifier: GPL-2.0
+# Copyright (c) 2013-2026 Igor Pecovnik, igor@armbian.com
+# This file is a part of the Armbian Build Framework https://github.com/armbian/build/
+#
+# Compile-cache backend: ccache (https://ccache.dev/).
+#
+# Wraps compiler invocations for kernel / u-boot / ATF / Crust through the
+# `ccache` binary and emits per-build hit/miss stats. Implements the generic
+# `compile_prepare_vars` (env exports) and `compile_wrapper_pre/post` hooks
+# (stats, also fired on interrupt). Per-artifact `*_make_config` hooks
+# inject CCACHE_UMASK into the env-i make envs since the kernel/u-boot
+# auto-passthrough only covers CCACHE_DIR.
+#
+# Auto-enabled by core when USE_CCACHE=yes / PRIVATE_CCACHE=yes is set, or
+# when the ccache-remote extension is requested (see
+# main_config_redefine_user_target in main-config.sh). Can also be enabled
+# explicitly via ENABLE_EXTENSIONS=ccache regardless of the USE_CCACHE
+# toggle.
+#
+# Mutually exclusive with other compile-cache extensions (sccache, …) — the
+# mutex is enforced in extension_prepare_config__ccache.
+#
+# Ordering invariant: env wiring lives in compile_prepare_vars__ccache,
+# which fires from prepare_compilation_vars (start-end.sh:20) — late
+# enough that every extension_prepare_config_* and the userpatches /
+# user_config phases have settled values like PRIVATE_CCACHE, and early
+# enough that ${CCACHE} substitution and PATH prefix propagate into the
+# arrays built by run_*_make_internal. Order is fixed by core, not by
+# alphabetical hook name resolution.
+
+# Cross-hook state for SHOW_CCACHE pre→post (dir-size diff calculation).
+declare -g __ext_ccache_dir_actual=""
+declare -g __ext_ccache_dir_size_before=""
+
+# Mutually-exclusive list of compile-cache extensions. Update when a new
+# backend extension is added (sccache, …).
+declare -g -a __ext_ccache_conflicting_exts=("sccache")
+
+function extension_prepare_config__ccache() {
+	local other
+	for other in "${__ext_ccache_conflicting_exts[@]}"; do
+		if [[ ",${ENABLE_EXTENSIONS:-}," == *",${other},"* ]]; then
+			exit_with_error "${EXTENSION}: 'ccache' and '${other}' extensions are mutually exclusive — choose one compile-cache backend"
+		fi
+	done
+	# All env setup lives in compile_prepare_vars__ccache (called from
+	# prepare_compilation_vars). See ordering invariant in the file header.
+}
+
+# Main env setup. Runs from prepare_compilation_vars — late enough that
+# values set by other extensions (PRIVATE_CCACHE from ccache-remote) and
+# by userpatches/lib.config / user_config hooks are settled, and early
+# enough that ${CCACHE} substitution in run_*_make_internal sees the
+# exported value.
+function compile_prepare_vars__ccache() {
+	# Make the binary substitution available wherever scripts reference
+	# ${CCACHE} (kernel-make.sh:60, uboot.sh:259, atf.sh:86, crust.sh:55,59).
+	export CCACHE="ccache"
+
+	# Drop a wrapper directory in front of PATH so bare `gcc` invocations
+	# also route through ccache via /usr/lib/ccache symlinks. This becomes
+	# part of the PATH captured by kernel-make.sh:23 and uboot.sh:243 when
+	# they build the env-i make environment.
+	export PATH="/usr/lib/ccache:${PATH}"
+
+	# private ccache dir avoids permission issues when build is run as root
+	# while user invokes via sudo; see https://ccache.samba.org/manual.html#_sharing_a_cache
+	if [[ "${PRIVATE_CCACHE}" == "yes" && -z "${CCACHE_DIR}" ]]; then
+		export CCACHE_DIR="${SRC}/cache/ccache"
+	elif [[ -n "${CCACHE_DIR}" ]]; then
+		# CCACHE_DIR set by user or another extension: make sure it is exported.
+		export CCACHE_DIR
+	fi
+
+	# Shared-cache mode: world-rw so multiple users on a build host can share
+	# the same directory. ccache reads CCACHE_UMASK from env at write time;
+	# the *_make_config hooks below inject it into env-i make envs since
+	# kernel/uboot auto-passthrough only covers CCACHE_DIR.
+	if [[ -z "${CCACHE_UMASK}" && "${PRIVATE_CCACHE}" != "yes" ]]; then
+		export CCACHE_UMASK=000
+	elif [[ -n "${CCACHE_UMASK}" ]]; then
+		export CCACHE_UMASK
+	fi
+}
+
+# Inject CCACHE_UMASK into the given env-i make envs array if set. Core
+# kernel-make.sh / uboot.sh auto-pass CCACHE_DIR but not CCACHE_UMASK,
+# and env -i would otherwise drop it so ccache writes fall back to the
+# default umask — breaking world-rw guarantees for shared caches.
+function _ext_ccache_inject_umask() {
+	local -n envs="$1"
+	[[ -n "${CCACHE_UMASK}" ]] && envs+=("CCACHE_UMASK=${CCACHE_UMASK@Q}")
+	return 0
+}
+
+function kernel_make_config__ccache() { _ext_ccache_inject_umask common_make_envs; }
+function uboot_make_config__ccache() { _ext_ccache_inject_umask uboot_make_envs; }
+# ATF / Crust don't use env -i (their make runs in the host shell), so
+# CCACHE_UMASK propagates naturally from the export in compile_prepare_vars.
+# No make_config hook needed for them.
+
+function compile_wrapper_pre__ccache() {
+	display_alert "Clearing ccache statistics" "ccache" "ccache"
+	run_host_command_logged ccache --zero-stats
+
+	if [[ "${SHOW_CCACHE}" == "yes" ]]; then
+		display_alert "CCACHE_DIR" "${CCACHE_DIR:-"unset"}" "ccache"
+		display_alert "CCACHE_TEMPDIR" "${CCACHE_TEMPDIR:-"unset"}" "ccache"
+
+		__ext_ccache_dir_actual="$(ccache --show-config | grep "cache_dir =" | cut -d "=" -f 2 | xargs echo)"
+
+		local ccache_dir_size_before_human
+		__ext_ccache_dir_size_before="$(du -sb "${__ext_ccache_dir_actual}" | cut -f 1)"
+		ccache_dir_size_before_human="$(numfmt --to=iec-i --suffix=B --format="%.2f" "${__ext_ccache_dir_size_before}")"
+		display_alert "ccache dir size before" "${ccache_dir_size_before_human}" "ccache"
+
+		wait_for_disk_sync "before ccache config"
+		display_alert "ccache configuration" "ccache" "ccache"
+		run_host_command_logged ccache --show-config "&&" sync
+	fi
+
+	display_alert "Running ccache'd build..." "ccache" "ccache"
+}
+
+function compile_wrapper_post__ccache() {
+	local stats_output direct_hit direct_miss pct
+	stats_output=$(ccache --print-stats 2>&1 || true)
+	direct_hit=$(ccache_get_stat "${stats_output}" "direct_cache_hit")
+	direct_miss=$(ccache_get_stat "${stats_output}" "direct_cache_miss")
+	pct=$(ccache_hit_pct "${direct_hit}" "${direct_miss}")
+	display_alert "Ccache result" "hit=${direct_hit} miss=${direct_miss} (${pct}%)" "info"
+
+	# Backward-compat: invoke the legacy ccache_post_compilation hook so
+	# 3rd-party extensions that listened to it (e.g. ccache-remote) continue
+	# to receive the event and can use ccache_get_stat / ccache_hit_pct.
+	call_extension_method "ccache_post_compilation" <<- 'CCACHE_POST_COMPILATION'
+		*called after ccache-wrapped compilation completes (success or failure)*
+		Legacy hook preserved for backward compatibility; new extensions should
+		implement compile_wrapper_post__<name> instead.
+	CCACHE_POST_COMPILATION
+
+	if [[ "${SHOW_CCACHE}" == "yes" ]]; then
+		display_alert "Display ccache statistics" "ccache" "ccache"
+		run_host_command_logged ccache --show-stats --verbose
+
+		local ccache_dir_size_after ccache_dir_size_diff ccache_dir_size_diff_human
+		ccache_dir_size_after="$(du -sb "${__ext_ccache_dir_actual}" | cut -f 1)"
+		ccache_dir_size_diff="$((ccache_dir_size_after - __ext_ccache_dir_size_before))"
+		ccache_dir_size_diff_human="$(numfmt --to=iec-i --suffix=B --format="%.2f" "${ccache_dir_size_diff}")"
+		display_alert "ccache dir size change" "${ccache_dir_size_diff_human}" "ccache"
+	fi
+}
+
+# Parse a single numeric field from "ccache --print-stats" tab-separated
+# output; returns 0 if field not found or not numeric. Public name preserved
+# for backward compatibility with extensions/ccache-remote (which calls this
+# from its ccache_post_compilation__show_remote_stats hook).
+function ccache_get_stat() {
+	local stats_output="$1" field="$2"
+	local val
+	val=$(echo "${stats_output}" | grep "^${field}" | cut -f2 || true)
+	[[ "${val}" =~ ^[0-9]+$ ]] || val=0
+	echo "${val}"
+}
+
+# Hit percentage from hit and miss counts. Public name preserved for the
+# same backward-compat reason as ccache_get_stat.
+function ccache_hit_pct() {
+	local hit="$1" miss="$2"
+	local total=$((hit + miss))
+	if [[ ${total} -gt 0 ]]; then
+		echo $((hit * 100 / total))
+	else
+		echo 0
+	fi
+}

lib/functions/compilation/atf.sh

@@ -83,7 +83,17 @@ compile_atf() {
 
 	# - ENABLE_BACKTRACE="0" has been added to workaround a regression in ATF. Check: https://github.com/armbian/build/issues/1157
 
-	run_host_command_logged "CROSS_COMPILE='ccache ${ATF_COMPILER}'" CCACHE_BASEDIR="$(pwd)" "CC='ccache ${ATF_COMPILER}gcc'" \
+	call_extension_method "atf_make_config" <<- 'ATF_MAKE_CONFIG'
+		*Hook to customize ATF (TF-A) make environment before compilation*
+		Called right before invoking make for ATF. Extensions (compile-cache
+		wrappers like ccache/sccache, distcc setups, etc.) can modify env vars
+		exported by the make invocation; the actual wrap point is `${CCACHE}`
+		substituted into CROSS_COMPILE / CC below.
+		Available read-only variables:
+		  - ATF_COMPILER, ATF, BOARD, BRANCH, LINUXFAMILY
+	ATF_MAKE_CONFIG
+
+	run_host_command_logged "CROSS_COMPILE='${CCACHE} ${ATF_COMPILER}'" CCACHE_BASEDIR="$(pwd)" "CC='${CCACHE} ${ATF_COMPILER}gcc'" \
 		"CFLAGS='-fdiagnostics-color=always -Wno-error=attributes -Wno-error=incompatible-pointer-types'" \
 		"TF_LDFLAGS='${binutils_flags_atf}'" \
 		make ENABLE_BACKTRACE="0" LOG_LEVEL="40" BUILD_STRING="armbian" $target_make "${CTHREADS}"

lib/functions/compilation/compile-wrapper.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# SPDX-License-Identifier: GPL-2.0
+#
+# Copyright (c) 2013-2026 Igor Pecovnik, igor@armbian.com
+#
+# This file is a part of the Armbian Build Framework
+# https://github.com/armbian/build/
+
+# Generic compile-time wrapper, backend-agnostic.
+#
+# Wraps a compilation command (`make ...` invocation in run_host_command_logged
+# or similar) with two extension hooks:
+#
+#   compile_wrapper_pre   — called before the build. Extensions zero stats,
+#                           start long-lived helper servers, assert backend
+#                           health, etc.
+#   compile_wrapper_post  — called after the build (also on SIGINT/errexit via
+#                           the registered cleanup handler). Extensions show
+#                           stats, push final cache batches, etc.
+#
+# Extensions are identified by the conventional double-underscore suffix:
+#     compile_wrapper_pre__<extension_name>()
+#     compile_wrapper_post__<extension_name>()
+#
+# Default behavior with no extensions registered: passthrough — the command
+# runs unchanged. This makes the wrapper safe to drop in everywhere a
+# compilation invocation lives, without committing to any specific cache
+# backend.
+function do_with_compile_wrapper() {
+	# Register the post-hook as a cleanup handler BEFORE running pre hooks.
+	# A compile_wrapper_pre implementation may start a long-lived helper
+	# (e.g. `sccache --start-server`); if another pre hook then fails or the
+	# user interrupts during pre-hook execution, the post hook must still
+	# fire so backend cleanup (stop helpers, flush state) is not skipped.
+	add_cleanup_handler _do_with_compile_wrapper_run_post
+
+	call_extension_method "compile_wrapper_pre" <<- 'COMPILE_WRAPPER_PRE'
+		*pre-compilation hook for cache wrappers (ccache, sccache, …) and
+		similar backend-agnostic setup*
+		Called once right before the wrapped compilation command runs.
+		Implementations may zero stats counters, start a long-lived helper
+		process, validate that a remote backend is reachable, etc.
+		The matching compile_wrapper_post hook is guaranteed to fire even
+		if a later pre hook fails or the build is interrupted, so cleanup
+		of resources started here is safe to rely on.
+	COMPILE_WRAPPER_PRE
+
+	local build_exit_code=0
+	"$@" || build_exit_code=$?
+
+	# Remove and explicitly run the post-hook on the success path so it does
+	# not also fire from the cleanup handler at script exit.
+	execute_and_remove_cleanup_handler _do_with_compile_wrapper_run_post
+
+	return ${build_exit_code}
+}
+
+# Internal — invoked by do_with_compile_wrapper either directly on success or
+# via the cleanup-handler chain on interruption. Kept as a separate function
+# so it has a stable name to register with add_cleanup_handler.
+function _do_with_compile_wrapper_run_post() {
+	call_extension_method "compile_wrapper_post" <<- 'COMPILE_WRAPPER_POST'
+		*post-compilation hook for cache wrappers and similar*
+		Called once after the wrapped compilation command completes (success
+		or failure) or is interrupted. Implementations may display stats,
+		flush a remote cache write buffer, shut down a helper server, etc.
+	COMPILE_WRAPPER_POST
+}

lib/functions/compilation/crust.sh

@@ -46,10 +46,20 @@ compile_crust() {
 		return 0
 	fi
 
-	declare binutils_version binutils_flags_crust=""
+	declare binutils_version
 	binutils_version=$(env or1k-elf-ld.bfd --version | head -1 | cut -d ")" -f 2 | xargs echo -n)
 	display_alert "Binutils version for Crust" "${binutils_version}" "info"
 
+	call_extension_method "crust_make_config" <<- 'CRUST_MAKE_CONFIG'
+		*Hook to customize Crust make environment before compilation*
+		Called right before invoking make for Crust (both defconfig and target make).
+		Extensions (compile-cache wrappers like ccache/sccache, distcc setups, etc.)
+		can modify env vars exported by the make invocation; the actual wrap
+		point is `${CCACHE}` substituted into `CROSS_COMPILE` below.
+		Available read-only variables:
+		  - CRUST_COMPILER, BOARD, BRANCH, LINUXFAMILY
+	CRUST_MAKE_CONFIG
+
 	run_host_command_logged CCACHE_BASEDIR="$(pwd)" \
 		"CFLAGS='-fdiagnostics-color=always -Wno-error=attributes -Wno-error=incompatible-pointer-types'" \
 		make ${CRUSTCONFIG} "${CTHREADS}" "CROSS_COMPILE='$CCACHE $CRUST_COMPILER'"