Skip to content

docs(20): state what is supported before stating how it is designed - #577

Merged
Sunrisepeak merged 1 commit into
mainfrom
docs/round5-followups
Sep 6, 2026
Merged

docs(20): state what is supported before stating how it is designed#577
Sunrisepeak merged 1 commit into
mainfrom
docs/round5-followups

Conversation

@Sunrisepeak

Copy link
Copy Markdown
Member

Why

mcpp implements ONE mechanism, the island is a claim about the design, and
it sat where a reader meets it first — so it was read, more than once, as only
one thing is supported
. The paragraph immediately after it says SYCL is reached
through the island, so the document's own content already contradicted the
impression its opening left.

The real gap is that the multi-backend capability was never stated at all.

Measured

--accel which cfg(accelerator = …) fire
"cuda12.9+{sm_89}, vulkan1.2" both cuda and vulkan
"cuda12.9+{sm_89} vulkan1.2" (space) only cuda

The comma separates entries in the set; a space separates modifiers
within one entry. The "two-chunk accel" of the HIP and SYCL rules is not a
special grammar — it is this grammar, with one entry naming a programming model
and one naming a device.

What changed

  • docs/20 now opens with What is supported, and the one-mechanism
    statement follows as the explanation of how rather than as a limitation
    banner.
  • A new section, Several backends in one build, covers writing the source
    sets, and with it a failure the manifest can avoid.

The four examples write cfg(not(accelerator = "<its own>")). That is correct
for one backend and wrong for several: a CUDA build satisfies
not(accelerator = "vulkan") too, so the CPU implementation joins the link
beside the CUDA one and the seam's shared extern "C" symbols collide.
Measured:

ld: obj/src/cpu/impl.o: multiple definition of `impl';
    obj/src/cuda/impl.o: first defined here

Negating the whole set fixes it. The section also names the shape that needs no
such list — do not select at link time at all, which is what ggml does and what
ggml-org:llamacpp is built as — and says that choosing between them is a
property of the program, not of mcpp.

Also here

Round 5's ecosystem review and the plan's F2 pre-measurement, held back until
the release tag existed because pushing to main between the merge and the
dispatch moves the commit being released.

The pre-measurement changes F2's plan: round 3 recorded "blocked on a payload
matrix", and that no longer holdscuda-nvcc, cuda-cudart,
libcublas, cuda-cccl and libcurand are all published, and
<cub/cub.cuh> is the only external device include across all 186 translation
units. CUDA's shape turns out simpler than Vulkan's because it has no
generator.

"mcpp implements ONE mechanism, the island" is a claim about the DESIGN, and it
sat where a reader meets it first, so it was read -- more than once -- as "only
one thing is supported". The paragraph immediately after it says SYCL is reached
through the island, so the document's content already contradicted the
impression its opening left.

The real gap is that the multi-backend capability was never stated at all.
Measured:

  --accel "cuda12.9+{sm_89}, vulkan1.2"   both cfg(accelerator=…) fire
  --accel "cuda12.9+{sm_89} vulkan1.2"    only cuda

The comma separates ENTRIES in the set; a space separates MODIFIERS within one
entry. The "two-chunk accel" of the HIP and SYCL rules is not a special
grammar, it is this grammar with one entry naming a model and one naming a
device.

A new section covers writing the source sets for several backends, and with it
a failure the manifest can avoid: the four examples write
`cfg(not(accelerator = "<its own>"))`, which is correct for one backend and
wrong for several -- a CUDA build satisfies `not(accelerator = "vulkan")` too,
so the CPU implementation joins the link beside the CUDA one and the seam's
shared `extern "C"` symbols collide. Measured: `multiple definition of 'impl'`.
Negating the whole set fixes it, and the section also names the shape that
needs no such list: do not select at link time at all, which is what ggml does
and what `ggml-org:llamacpp` is built as.

Also lands round 5's ecosystem review and the plan's F2 pre-measurement, which
were held back until the release tag existed because pushing to main between
the merge and the dispatch moves the commit being released. The measurement
changes F2's plan: round 3's "blocked on a payload matrix" no longer holds, and
CUDA's shape turns out simpler than Vulkan's because it has no generator.
@Sunrisepeak
Sunrisepeak merged commit 9838933 into main Sep 6, 2026
36 checks passed
@Sunrisepeak
Sunrisepeak deleted the docs/round5-followups branch September 6, 2026 04:25
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.

2 participants