feat: support aarch64 hosts via a host_arch attribute

Every toolchain this module generates hardcodes
`exec_compatible_with = [linux, x86_64]` -- it is a string literal in the hub's
BUILD template, while target_compatible_with beside it is a format field. So on
an aarch64 host Bazel matches no cc toolchain at all and every C/C++ action fails
resolution, not just cross-compiles.

The binaries to fix that already exist: gcc-builds has published `-host-aarch64`
archives since 08072026, covering aarch64, armv7 and x86_64 targets for every GCC
version pinned to 08072026 or later (14.3.0, 15.2.0, 16.1.0 and 16.2.0). Only the
Starlark wiring was missing.

`host_arch` names the architecture the toolchain binaries RUN on. It defaults to
`rctx.os.arch`, so a native build on either architecture needs no configuration,
and it drives three things:

- which archive is fetched, via a host dimension on AVAILABLE_GCC_VERSIONS;
- `exec_compatible_with`, now a templated hub attribute defaulting to
  `[linux, {host_arch}]`, mirroring target_compatible_with;
- the builtin include layout.

That last one was a latent bug. A NATIVE build lays libstdc++ out flat
(`include/c++/<version>`) while a CROSS build nests it under the target triple,
and the existing code keyed that on `target_arch == x86_64` -- correct only
because every published build was x86_64-hosted. It is now keyed on
`host_arch == target_arch`, which is what the archives actually do: the
aarch64-hosted aarch64 build is flat, and the aarch64-hosted x86_64 one is
nested. Getting this wrong is quiet, because a nonexistent -isystem directory is
ignored and only surfaces later as a missing <string>.

Backwards compatible. Existing entries keep their exact URLs and digests, and the
binary prefix needs no host handling because _detect_binary_prefix already probes
the extracted archive. A hand-written `gcc_versions` in the old
`{version: {target: {url, sha256}}}` shape still works and is read as
x86_64-hosted; combining it with a non-x86_64 host fails with a message saying
what to write instead.

Verified all four host/target combinations (plus aarch64-hosted armv7) resolve,
fetch the archive whose ELF machine matches their host_arch, and declare only
include directories that exist -- and that the x86_64-hosted paths are unchanged.
//tests/host_arch asserts the aarch64-hosted compiler is an ARM ELF by reading
e_machine, so it runs anywhere; it fails if pointed at the x86_64-hosted cross
toolchain. It is skipped for 12.5.0 and 13.4.0, whose releases publish no
aarch64-hosted build, as //tests/lld is for the versions built without lld.

Author: janickm

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()

docs/README.md

@@ -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": [],
+    }),
+)

docs/defs.md

@@ -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."