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

extensions/ccache.sh

@@ -0,0 +1,205 @@
+#
+# 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_wrapper_pre/post` hooks (so stats are still shown on interrupt)
+# and the per-component `*_make_config` hooks (so the env is set up uniformly
+# regardless of which artifact is being built).
+#
+# Auto-enabled by core when USE_CCACHE=yes or 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: all per-build env wiring (CCACHE_DIR, CCACHE_UMASK,
+# PATH prefix, ${CCACHE}) is set inside the *_make_config hooks, which fire
+# during the compile phase — after every extension_prepare_config_* hook
+# has run. This makes the extension safe against other extensions that set
+# USE_CCACHE / PRIVATE_CCACHE late in extension_prepare_config (e.g.
+# ccache-remote) regardless of alphabetical ordering.
+
+# 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 / CCACHE_DIR / CCACHE_UMASK / PATH setup lives in the
+	# *_make_config hooks — see ordering invariant in the file header.
+}
+
+# Resolve the cache directory ccache will use and export it so child shells
+# (run_host_command_logged spawns a new bash; ccache reads CCACHE_DIR from
+# env, not from bash globals) pick it up. Also exports CCACHE_UMASK in the
+# shared-cache case so multi-user shared caches stay world-rw.
+#
+# Reads USE_CCACHE / PRIVATE_CCACHE at call time so values set late in
+# extension_prepare_config (e.g. by ccache-remote) are respected without
+# any ordering dependency.
+function _ext_ccache_export_env() {
+	# Make the binary substitution available wherever scripts reference ${CCACHE}.
+	export CCACHE="ccache"
+
+	# 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.
+	if [[ -z "${CCACHE_UMASK}" && "${PRIVATE_CCACHE}" != "yes" ]]; then
+		export CCACHE_UMASK=000
+	elif [[ -n "${CCACHE_UMASK}" ]]; then
+		export CCACHE_UMASK
+	fi
+}
+
+# Prepend /usr/lib/ccache to the PATH entry already present in
+# common_make_envs (placed there by run_*_make_internal so that, for
+# example, kernel-make.sh inserts ${PYTHON3_INFO[USERBASE]}/bin for dtb
+# checks). We must not append a second `PATH=` entry because `env -i`
+# keeps only the last one, which would drop the python tools prefix and
+# cause builds that depend on those tools to fail only when ccache is
+# enabled.
+function _ext_ccache_prepend_path_in_envs() {
+	local -n envs="$1"
+	local i found=0
+	for i in "${!envs[@]}"; do
+		if [[ "${envs[$i]}" == PATH=* || "${envs[$i]}" == "PATH='"* ]]; then
+			# Strip leading "PATH=" or "PATH='" and trailing "'"
+			local existing="${envs[$i]#PATH=}"
+			existing="${existing#\'}"
+			existing="${existing%\'}"
+			envs[$i]="PATH='/usr/lib/ccache:${existing}'"
+			found=1
+			break
+		fi
+	done
+	if (( ! found )); then
+		envs+=("PATH='/usr/lib/ccache:${PATH}'")
+	fi
+}
+
+# Per-artifact make hooks. Settles env at compile time, which is after every
+# extension_prepare_config_* — so PRIVATE_CCACHE / CCACHE_DIR set late by
+# ccache-remote (or any other extension) is honoured here.
+function kernel_make_config__ccache() {
+	_ext_ccache_export_env
+	_ext_ccache_prepend_path_in_envs common_make_envs
+}
+
+function uboot_make_config__ccache() {
+	_ext_ccache_export_env
+	_ext_ccache_prepend_path_in_envs uboot_make_envs 2> /dev/null || true
+}
+
+function atf_make_config__ccache() {
+	_ext_ccache_export_env
+	# ATF build does not use a common_make_envs-style array; ${CCACHE}
+	# substitution inside `CROSS_COMPILE='${CCACHE} ${ATF_COMPILER}'`
+	# (set in atf.sh after this hook runs) is enough. PATH prepend is
+	# inherited from the caller env.
+}
+
+function crust_make_config__ccache() {
+	_ext_ccache_export_env
+	# Same as ATF: Crust's make line consumes ${CCACHE} directly.
+}
+
+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}"