Skip to content

ci: let the coverage gate see every backend, and document the one it caught - #556

Merged
godofecht merged 3 commits into
mainfrom
ci/coverage-sees-all-backends
Aug 18, 2026
Merged

godofecht merged 3 commits into
mainfrom
ci/coverage-sees-all-backends

Conversation

@godofecht

@godofecht godofecht commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor

Found by opening #555, and then immediately proved by merging it.

The gap

check_doc_coverage.py discovered backends by matching *_generator.py, *_codegen.py and *_compiler.py. The BPF target is bpf_target.py, so a whole new compilation target would have merged without the coverage gate asking for a documentation page.

Added _target and _backend to the suffix list, with a test enumerating all five conventions against a temporary tree.

The gate then caught it for real

When #555 merged and I rebased this branch onto main, the checker did exactly what it was built to do:

backend       9/10   covered   exempt   0   problems   0   uncovered   1

1 problem(s):
  backend:bpf_target has no documented home

So this PR also carries docs/language/bpf.md, written from the implementation rather than from the commit messages:

  • the CLI, every flag
  • the fixed ABI: bpfel triple, 64-bit pointers, and the verifier's 512-byte stack limit
  • the section and license metadata the kernel reads, with the actual IR it produces
  • the ten symbols the target refuses, because a BPF program runs with no userspace runtime (malloc, free, _Znwm, __cxa_throw, …)
  • the entry-point naming rule and why it exists: the target lowers with --llvm so the definition carries the plain Flow name, while flow_export_<name> is a C-backend alias. Searching only for the alias is what made every build on that branch fail for eight runs.
  • the toolchain caveat, the same as wasm32: Apple's clang has no BPF backend

Filed under Targets & interop in the sidebar, next to WebAssembly.

Validation

  • check_doc_coverage.py: 10/10 backends, every feature covered
  • wiki_nav.py consistent, check_doc_links.py clean including fragments
  • check_doc_examples.py --check-ledger clean
  • Unit suite 1510 passed, 2 skipped
  • ruff check src clean

godofecht and others added 3 commits August 18, 2026 17:54
Backend discovery matched *_generator.py, *_codegen.py and *_compiler.py.
A BPF target sitting unreviewed on codex/bpfel-target is named
bpf_target.py, so a whole new compilation target would have merged without
the coverage gate asking for a page.

Added _target and _backend. The nine current backends are unaffected; the
point is the next one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Merging #555 gave the coverage checker a tenth backend, and with _target in
the suffix list it did what it was built to do:

    backend:bpf_target has no documented home

So here is the page. It covers the CLI, the fixed ABI (bpfel triple, 64-bit
pointers, the verifier's 512-byte stack limit), the section and license
metadata the kernel reads, and the symbols the target refuses because a BPF
program has no userspace runtime.

It also records the entry-point naming rule and why it exists: the target
lowers with --llvm, so the definition carries the plain Flow name, while
flow_export_<name> is a C-backend alias. Looking only for the alias is what
made every build on that branch fail.

The toolchain caveat is the same as wasm32: Apple's clang has no BPF backend,
so this is a Linux-only build.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@godofecht godofecht changed the title ci: let the coverage gate see every backend naming convention ci: let the coverage gate see every backend, and document the one it caught Aug 18, 2026
@godofecht
godofecht merged commit d074a00 into main Aug 18, 2026
21 checks passed
@godofecht
godofecht deleted the ci/coverage-sees-all-backends branch August 18, 2026 18:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant