[DOCS] Write down the cross-compilation promise (README + installation docs), with explicit support-status tags

[oberstet]

See also:

• [DOCS] Write down the cross-compilation promise (README + installation docs), with explicit support-status tags zlmdb#145
• [DOCS] Pin the long-term goal: Crossbar.io on Buildroot/Yocto, cross-built for riscv64 — as an explicitly tagged **roadmap** promise crossbar#2280

---

Why

PR #1934 proposed changing NVX compiler-flag selection for external cross toolchains (Yocto/OpenEmbedded, Buildroot). Reviewing it surfaced a more basic problem:

we cannot say whether that PR fixes a deviation from promised behaviour, because we never wrote the promise down.

Where cross-compilation is mentioned today:

• docs/changelog.rst:70 ([BUG] Incorrect machine is detected while cross compiling #1834/Use sysconfig.get_platform for machine detection #1835) — "The default architecture target is now the portable baseline for all build contexts (wheels, local source installs, and cross-compilation). The target architecture is detected via sysconfig.get_platform() so the correct baseline is chosen when cross-compiling."
• src/autobahn/nvx/_compile_args.py module docstring — "never hands a cross-compilation toolchain the host-only -march=native flag" and, at :238-240, "Defaulting to 'safe' rather than -march=native is what makes cross-compilation work out of the box". This is published — via sphinx-autoapi, despite the leading underscore.

Where it is not mentioned: README.md, docs/installation.rst, or anywhere else a user or integrator would look. Grepping the docs tree returns hits only in the changelog, _compile_args.py and its test.

So an integrator has to discover our cross-build behaviour by hitting a compiler error. Meanwhile the docstring makes the strongest claim we have — "works out of the box" — with no CI job that cross-compiles anything behind it. That claim is aspiration, not fact, and it is published as documentation.

This issue is about fixing the promise, not the code.

Support-status vocabulary (to be used identically in autobahn, zlmdb, crossbar)

• Supported — named targets, gated in CI: Tier 1 per-commit, Tier 2 nightly.
• Best-effort — expected to work, not gated in CI; bug reports welcome.
• Roadmap — intended direction, not yet backed by tests.

Test tiers (vocabulary, for the docs; implementation is out of scope here)

• Tier 1 — cross-build ("baking"): the native extension cross-compiles for the target and the artifact is verified (e.g. readelf -h → expected machine, plus an import/functional smoke test of the built module). Fast; intended to
  run on every commit.
• Tier 2 — run on target: boot the target (QEMU system emulation) and run the project's own test suite there. Slow; intended to run nightly.

Reference target for both tiers: riscv64 (rv64gc / lp64d) via Buildroot, cross-built on x86-64, glibc first and musl second, booted under qemu-system-riscv64. riscv64 is deliberately chosen: it is a true cross-build
(our aarch64 wheels are built natively under QEMU-user, which never exercises the cross path at all), and we publish no riscv64 wheels, so every riscv64 user must build from source.

The matrix to publish

artifact	Tier 1 (cross-build)	Tier 2 (run on target)
autobahn	roadmap → supported once the job lands	roadmap
zlmdb	roadmap → supported once the job lands	roadmap
crossbar	roadmap	roadmap (ultimate goal)

Rows move up as tiers land. Nothing may claim more than it can demonstrate.

What to write

1. README.md — a short "Cross-compilation and embedded targets" subsection stating the promise and its current status tag, linking to the installation docs. This is a top-level promise; it should not be buried.
2. docs/installation.rst — the substance:
   • what we guarantee today: with AUTOBAHN_ARCH_TARGET unset we never emit a host-specific -march (in particular never -march=native); the architecture baseline is chosen from the target as reported by sysconfig.get_platform(); unknown/unrecognised targets get no -march at all and the toolchain's own flags govern code generation;
   • the documented escape hatch: AUTOBAHN_ARCH_TARGET=native|safe, what each means, and when a distro/integrator should set it;
   • the status tags per target, per the matrix above;
   • a note that Buildroot/Yocto-class toolchains supply their own -march/-mtune/-mcpu, and what we do about that (see the open decision below).
3. Fix the overclaim in src/autobahn/nvx/_compile_args.py:238-240: "what makes cross-compilation work out of the box" → wording that matches what we actually back. This text is published via autoapi, so it is a promise whether we meant it as one or not.

Open decision to record while writing this

#1934 implicitly invented a precedence rule that we have never stated. Writing the docs forces the question, and the answer belongs in installation.rst:

What is authoritative about the target architecture? Explicit
AUTOBAHN_ARCH_TARGET > a cross toolchain signal (CC/CROSS_COMPILE) >
sysconfig.get_platform()?

This matters because the underlying report in #1934 is that sysconfig.get_platform() returned the host (linux-x86_64) under Yocto while targeting ARM — i.e. the mechanism our changelog names as the guarantee failed, one layer below where #1934 patches. Whatever we decide, an explicit "we do not second-guess an externally managed toolchain" rule (or its opposite) must be written down before any code change implements it. Tracked separately; see the companion issue for the sysconfig target-detection bug.

Non-goals (separate issues, to be filed later)

• Implementing the Tier 1 / Tier 2 CI jobs.
• Factoring shared cross-build CI machinery into wamp-cicd.
• Changing _compile_args.py behaviour (beyond correcting the overclaiming
  docstring text).

Acceptance criteria

• README.md carries a cross-compilation / embedded-targets subsection with
  an explicit status tag
• docs/installation.rst documents the guarantee, the
  AUTOBAHN_ARCH_TARGET escape hatch, the per-target status tags, and the
  Tier 1 / Tier 2 definitions
• The _compile_args.py "works out of the box" claim is corrected to match
  what is actually backed
• Every claim in the new text is either backed by an existing test or
  explicitly tagged roadmap — no unbacked assertions
• The status vocabulary and matrix are worded identically to the
  corresponding zlmdb and crossbar issues