Harden ABI detection for cross-build wrappers (#19)

* Add explicit STACKMAN_ABI override support

* Normalize Windows ARM64 ABI token and keep alias compatibility

* Add ABI detection diagnostics and target-triple mismatch warning

* Use CFLAGS in target-triple probe and soften mismatch warning

* Document ABI detection hardening in changelog

* Address PR review feedback on changelog and ABI override

* Skip target probing when STACKMAN_ABI override is set

Author: kristjanvalur

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added explicit `STACKMAN_ABI` override support in the Makefile and ABI probe script for deterministic cross-build packaging
+
+### Changed
+- Normalized Windows ARM64 ABI naming to `win_arm64` and kept compatibility mapping for legacy `win_aarch64` inputs
+- ABI probe diagnostics now query compiler target triple and emit clearer mismatch guidance when target intent is not fully propagated through wrapper/toolchain settings
+- Target triple probing now prefers `CC` with `CFLAGS` (with fallback probing) so clang-style cross-target flags are reflected in secondary detection
+
 ## [1.2.2] - 2026-06-05
 
 ### Changed

Makefile

@@ -17,8 +17,14 @@ CXX = $(PLATFORM_PREFIX)-g++
 LD = $(PLATFORM_PREFIX)-ld
 AR = $(PLATFORM_PREFIX)-ar
 endif
-# run c preprocessor with any cflags to get cross compilation result, then run regular compile in native
+# Allow explicit ABI selection for deterministic cross-build packaging.
+# If not provided, auto-detect from compiler macros.
+ifeq ($(strip $(STACKMAN_ABI)),)
 ABI := $(shell sh tools/abiname.sh "$(CC)" "$(CFLAGS)")
+else
+# Accept legacy alias for backward compatibility.
+ABI := $(patsubst win_aarch64,win_arm64,$(strip $(STACKMAN_ABI)))
+endif
 ifndef ABI
 $(error Could not determine platform)
 endif

stackman/platforms/platform.h

@@ -44,7 +44,7 @@
 #elif defined(_M_ARM64)
 #include "switch_arm64_msvc.h" /* MS Visual Studio on ARM */
 #define _STACKMAN_PLATFORM arm64_msvc
-#define _STACKMAN_ABI win_aarch64
+#define _STACKMAN_ABI win_arm64
 #endif
 
 

tools/abiname.sh

@@ -10,6 +10,54 @@
 # run the provided code.
 set -eu
 here=$(dirname "$0")
+
+canonicalize_abi() {
+	case "$1" in
+		win_aarch64) printf '%s\n' "win_arm64" ;;
+		*) printf '%s\n' "$1" ;;
+	esac
+}
+
+detect_target_triple() {
+	# Prefer querying with CFLAGS so explicit target flags (for example
+	# --target=... in clang-based cross builds) are reflected.
+	if ${CC} ${CFLAGS} -dumpmachine >/dev/null 2>&1; then
+		${CC} ${CFLAGS} -dumpmachine
+		return 0
+	fi
+	if ${CC} ${CFLAGS} --print-target-triple >/dev/null 2>&1; then
+		${CC} ${CFLAGS} --print-target-triple
+		return 0
+	fi
+	# Fall back to no CFLAGS in case unrelated build flags make the query fail.
+	if ${CC} -dumpmachine >/dev/null 2>&1; then
+		${CC} -dumpmachine
+		return 0
+	fi
+	if ${CC} --print-target-triple >/dev/null 2>&1; then
+		${CC} --print-target-triple
+		return 0
+	fi
+	printf '%s\n' ""
+}
+
+abi_from_target_triple() {
+	triple=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+	case "${triple}" in
+		*x86_64*apple-darwin*|*x86_64*darwin*) printf '%s\n' "darwin_x86_64" ;;
+		*arm64*apple-darwin*|*aarch64*apple-darwin*|*arm64*darwin*|*aarch64*darwin*) printf '%s\n' "darwin_arm64" ;;
+		*x86_64*linux*) printf '%s\n' "sysv_amd64" ;;
+		*i?86*linux*) printf '%s\n' "sysv_i386" ;;
+		*aarch64*linux*) printf '%s\n' "aarch64" ;;
+		*arm*linux*gnueabi*|*armv7*linux*|*armv6*linux*) printf '%s\n' "arm32" ;;
+		*riscv64*linux*) printf '%s\n' "riscv64" ;;
+		*aarch64*w64*mingw*|*arm64*windows*|*aarch64*windows*) printf '%s\n' "win_arm64" ;;
+		*x86_64*w64*mingw*|*x86_64*windows*) printf '%s\n' "win_x64" ;;
+		*i?86*w64*mingw*|*i?86*windows*) printf '%s\n' "win_x86" ;;
+		*) printf '%s\n' "" ;;
+	esac
+}
+
 mkdir -p "${here}/tmp"
 # Clean up any stale temp files first
 rm -f "${here}/tmp"/abiname*.c "${here}/tmp"/abiname*.c.out
@@ -18,8 +66,27 @@ tmp=$(mktemp "${here}/tmp/abinameXXX.c")
 #1 create the preprocessed file
 CC=${1:-cc}
 CFLAGS=${2:-}
+ABI_OVERRIDE=${3:-${STACKMAN_ABI:-}}
+if [ -n "${ABI_OVERRIDE}" ]; then
+	abi=$(canonicalize_abi "${ABI_OVERRIDE}")
+	if [ -n "${STACKMAN_ABI_DEBUG:-}" ] || [ -n "${STACKMAN_ABI_TRACE:-}" ]; then
+		printf '%s\n' "stackman abiname: cc=${CC} target=override-skip abi=${abi} source=override" >&2
+	fi
+	printf '%s\n' "${abi}"
+	exit 0
+fi
+target_triple=$(detect_target_triple)
 ${CC} ${CFLAGS} -I${here}/../stackman -E -o "${tmp}" "${here}/abiname.c"
 #2 compile resulting file
 cc -o "${tmp}.out" "${tmp}"
 #3 run it
-"${tmp}.out"
+abi=$("${tmp}.out")
+abi=$(canonicalize_abi "${abi}")
+target_abi=$(abi_from_target_triple "${target_triple}")
+if [ -n "${target_abi}" ] && [ "${target_abi}" != "${abi}" ]; then
+	printf '%s\n' "warning: stackman ABI mismatch: compiler target '${target_triple}' suggests '${target_abi}', macro probe selected '${abi}'. This usually means target intent was not fully propagated (flags/wrapper selection). Consider setting STACKMAN_ABI explicitly for deterministic packaging." >&2
+fi
+if [ -n "${STACKMAN_ABI_DEBUG:-}" ] || [ -n "${STACKMAN_ABI_TRACE:-}" ]; then
+	printf '%s\n' "stackman abiname: cc=${CC} target=${target_triple:-unknown} abi=${abi} source=macro" >&2
+fi
+printf '%s\n' "${abi}"