feat: support aarch64 hosts via a host_arch attribute

MODULE.bazel

@@ -33,6 +33,17 @@ gcc_toolchains = use_extension("//toolchain:module_extensions.bzl", "gcc_toolcha
     ]
 ]
 
+# An aarch64-HOSTED toolchain, for //tests/host_arch. Deliberately not registered: its
+# binaries are ARM, so it cannot execute on an x86_64 CI machine -- the test only inspects
+# the fetched archive.
+gcc_toolchains.toolchain(
+    name = "gcc_toolchain_aarch64_host",
+    gcc_version = "14.3.0",
+    host_arch = "aarch64",
+    target_arch = "aarch64",
+)
+use_repo(gcc_toolchains, "gcc_toolchain_aarch64_host")
+
 # Dev Dependencies (for examples/)
 # ===============================
 bazel_dep(name = "rules_foreign_cc", version = "0.15.1", dev_dependency = True)

README.md

@@ -6,7 +6,8 @@ performance and portability. You can find the comprehensive documentation under
 
 ## Features
 
-- **Multi-architecture**: Support for x86_64, aarch64, and armv7 Linux targets.
+- **Multi-architecture**: Support for x86_64, aarch64, and armv7 Linux targets,
+  hosted on x86_64 or aarch64.
 - **Hermetic**: Fully self-contained with no system dependencies.
 - **Optimized**: Reduced toolchain sizes and improved build performance.
 - **Fortran Support**: Complete Fortran compilation, including OpenMP support.
@@ -42,7 +43,7 @@ The toolchain has been optimized to reduce size and improve build performance th
 
 * **First-party Code**: Your repository contains C/C++/Fortran code.
 * **Sanitizer Testing**: Need to run sanitizers (asan, lsan, tsan, ubsan) on your code.
-* **Cross-compilation**: Build for Linux armv7 or aarch64 from x86_64.
+* **Cross-compilation**: Build for Linux armv7, aarch64 or x86_64 from x86_64 or aarch64.
 * **Portability**: Create binaries compatible with any Linux distribution.
 * **Reproducibility**: Ensure consistent builds across development and CI environments.
 * **Remote Execution**: Use with Bazel RBE for distributed builds.

WORKSPACE

@@ -41,7 +41,7 @@ load("@bazel_lib//lib:repositories.bzl", "bazel_lib_dependencies")
 
 bazel_lib_dependencies()
 
-load("//toolchain:defs.bzl", "ARCHS", "gcc_register_toolchain")
+load("//toolchain:defs.bzl", "ARCHS", "gcc_declare_toolchain", "gcc_register_toolchain")
 
 gcc_register_toolchain(
     name = "gcc_toolchain_aarch64",
@@ -58,6 +58,16 @@ gcc_register_toolchain(
     target_arch = ARCHS.x86_64,
 )
 
+# An aarch64-HOSTED toolchain, for //tests/host_arch. DECLARED, not registered: its
+# binaries are ARM, so it cannot execute on an x86_64 CI machine -- the test only inspects
+# the fetched archive.
+gcc_declare_toolchain(
+    name = "gcc_toolchain_aarch64_host",
+    gcc_version = "14.3.0",
+    host_arch = ARCHS.aarch64,
+    target_arch = ARCHS.aarch64,
+)
+
 load("@rules_foreign_cc//foreign_cc:repositories.bzl", "rules_foreign_cc_dependencies")
 
 rules_foreign_cc_dependencies()

tests/host_arch/BUILD.bazel

@@ -0,0 +1,42 @@
+# Copyright (c) Thulio Ferraz Assis 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@rules_shell//shell:sh_test.bzl", "sh_test")
+
+# The aarch64-hosted toolchain, declared (not registered) as @gcc_toolchain_aarch64_host.
+# Its binaries are ARM, so they cannot be RUN on an x86_64 CI machine; this inspects the
+# fetched archive instead, which works on any host.
+#
+# `include` carries the builtin header tree, so requiring it as data also proves the layout
+# the toolchain declares is the layout the archive actually has -- a nonexistent -isystem
+# path is otherwise ignored silently, surfacing much later as a missing <string>.
+#
+# gcc-builds only publishes -host-aarch64 archives from the 08072026 release on, so the
+# versions pinned to older releases have no aarch64-hosted build to inspect and the test is
+# skipped for them, as in //tests/lld. Being incompatible keeps the target unanalyzed, so
+# the archive that does not exist is never fetched.
+sh_test(
+    name = "host_arch_test",
+    srcs = ["host_arch_test.sh"],
+    data = [
+        "@gcc_toolchain_aarch64_host//:gcc",
+        "@gcc_toolchain_aarch64_host//:include",
+    ],
+    env = {"GCC_FILES": "$(locations @gcc_toolchain_aarch64_host//:gcc)"},
+    target_compatible_with = select({
+        "//toolchain:gcc_version_12_5_0": ["@platforms//:incompatible"],
+        "//toolchain:gcc_version_13_4_0": ["@platforms//:incompatible"],
+        "//conditions:default": [],
+    }),
+)

tests/host_arch/host_arch_test.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Copyright (c) Thulio Ferraz Assis 2026
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# An aarch64-hosted toolchain must ship ARM binaries. Verified by inspecting the archive
+# rather than running it, so this test works on any host.
+
+set -euo pipefail
+
+gcc=""
+for f in ${GCC_FILES}; do
+    if [[ "${f}" == *-gcc ]]; then
+        gcc="${f}"
+        break
+    fi
+done
+
+if [[ -z "${gcc}" ]]; then
+    echo >&2 "FAIL: no *-gcc among the toolchain's compiler files: ${GCC_FILES}"
+    exit 1
+fi
+
+# ELF e_machine, at offset 18, little-endian: 0x00b7 is EM_AARCH64, 0x003e is x86-64. An
+# x86_64-hosted build here would mean the toolchain cannot run on an aarch64 machine at
+# all, which is the bug the host_arch attribute exists to fix.
+readonly machine="$(od -An -tx1 -j18 -N2 "${gcc}" | tr -d ' \n')"
+if [[ "${machine}" != "b700" ]]; then
+    echo >&2 "FAIL: ${gcc} has e_machine 0x${machine}, want 0xb7 (EM_AARCH64)."
+    exit 1
+fi
+
+echo "PASS: the aarch64-hosted toolchain ships ARM binaries."