Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#1,935 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
52/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
build-system, documentation

Direzione di ricerca

Inizia da README.md, docs/installation.rst e dal testo pubblicato in src/autobahn/nvx/_compile_args.py intorno alle righe 238-240; esamina i riferimenti esistenti alla compilazione incrociata e il test correlato. Registra la regola autorevole per il rilevamento della destinazione e allinea il vocabolario degli stati e la matrice con le issue collegate di zlmdb e crossbar. Il lavoro è completato quando la documentazione richiesta e la correzione dell’affermazione eccessiva sono complete, e le affermazioni non supportate sono contrassegnate come roadmap.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

docs enhancement feature

See also:

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 (#1834/#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
Lingua principale
Python
Stelle
2.5k
Fork
767
Merge medio
1g 1h
PR unite (30g)
23

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di crossbario/autobahn-python

Tutte le issue di crossbario/autobahn-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.