Repository navigation
quest: plan generated C bindings, park the hand-written libmoq quests #4300
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| # Generated C bindings | ||
|
|
||
| ## Goal | ||
|
|
||
| C programs use moq through a C API generated from moq-ffi, shipped as the | ||
| `moq-c` package with CMake target `moq::c`, so the hand-written libmoq ABI is | ||
| deleted and C tracks every moq-ffi change the way Go, Swift, Kotlin, Python, | ||
| Dart, and C++ already do. The C API shape follows moq-ffi and breaks C users | ||
| once. The C++ package and the OBS plugin are out of scope; they already sit on | ||
| moq-ffi through [C++ through moq-ffi](/quest/m1/cpp/README.md). | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided: | ||
|
|
||
| - The generator is a C backend in the `kixelated/uniffi-bindgen-cpp` fork, | ||
| beside the C++ one, so both share its parsing, async, and error plumbing and | ||
| one pinned tool covers both. No mature upstream C generator exists; uniffi | ||
| itself only emits the low-level scaffolding header. | ||
| - Async calls take a completion callback and user data and return a task; | ||
| freeing the task cancels the call. Callbacks run on moq's dispatcher thread | ||
| by default, or on the host's own loop through `moq_set_dispatcher` and | ||
| `moq_work_run`, the C form of `moq::set_executor`. Streams are repeated calls. | ||
| This removes the trampolines and lock-order rules libmoq's single callback | ||
| thread forced on hosts like OBS. | ||
| - Errors, records, and names mirror the C++ package: calls return `moq_error *` | ||
| (NULL on success) with `moq_error_message()`, results come through | ||
| out-params, records are owned structs with `moq_<type>_free`, and names are | ||
| the uniffi names in snake case. | ||
| - The generated package takes over the `moq-c` name and `moq::c` target that | ||
| #4288 gives the hand-written crate, so C users migrate once. Its first release | ||
| is 0.8.0, a minor bump over the hand-written 0.7.x. | ||
| - Docs change inline: the consumer quest rewrites `doc/lib/c`, and retirement | ||
| adds an upgrade note. No separate guide. | ||
|
|
||
| The line owns the end-to-end check: every `doc/lib/c` sample and the C interop | ||
| client build and run against the released 0.8.0 archive, not only in-tree. | ||
|
|
||
| The hand-written crate's open feature quests are parked in m3 until this line | ||
| retires it: [fetch](/quest/m3/libmoq-fetch.md), | ||
| [hidden](/quest/m3/libmoq-hidden.md), | ||
| [CMake library](/quest/m3/libmoq-cmake-lib.md), and | ||
| [shutdown](/quest/m3/libmoq-shutdown.md). | ||
|
|
||
| ## Quests | ||
|
|
||
| - [C backend](/quest/m1/c/backend.md) - the fork emits an ergonomic C header and implementation from moq-ffi, with its own tests | ||
| - [moq-c package](/quest/m1/c/package.md) - the generated header ships as `moq-c` 0.8.0 with `moq::c`, pkg-config, and a release workflow | ||
| - [C consumers](/quest/m1/c/consumers.md) - the C interop client and `doc/lib/c` samples move onto the generated API | ||
| - [Retire libmoq](/quest/m1/c/retire.md) - the hand-written crate is deleted after its final release points at the generated package | ||
|
|
||
| ## Related | ||
|
|
||
| - [C++ through moq-ffi](/quest/m1/cpp/README.md) - the generator fork and package recipe this line extends | ||
| - [libmoq becomes moq-c](/quest/m1/moq-c.md) - the rename whose name this line inherits | ||
| - [FFI shape](/quest/m1/ffi-shape/README.md) - reshapes moq-ffi, which the generated C then follows for free |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| # [L] C backend in the bindings generator | ||
|
|
||
| ## Goal | ||
|
|
||
| `uniffi-bindgen-cpp` (the `kixelated` fork) gains a C backend that turns | ||
| moq-ffi's uniffi metadata into an ergonomic C header and implementation, in the | ||
| shape the [line](/quest/m1/c/README.md) decided: completion callbacks with a | ||
| cancelling task handle, a pluggable dispatcher, `moq_error *` returns with | ||
| out-params, owned record structs with free functions, and snake-case uniffi | ||
| names. | ||
|
|
||
| ## Plan | ||
|
|
||
| - Build on the fork's C++ backend: it already walks the metadata, serializes | ||
| records and errors through `RustBuffer`, and drives `rust_future_poll` on a | ||
| dispatcher. The C backend emits the same calls behind a C surface, so the | ||
| generated implementation may itself be C++ compiled into the package, as long | ||
| as the public header is plain C (C99 or C11; say which). | ||
| - Cover every construct moq-ffi uses today: objects (handles), records, enums, | ||
| the one error type, async methods, and byte buffers. moq-ffi has no callback | ||
| interfaces; refuse them loudly rather than emit something half-working. | ||
| - The fork's test suite gains C fixtures for each construct, including | ||
| cancelling a pending task and running callbacks through a custom dispatcher. | ||
| - Offer the backend to the LiveKit or NordSecurity upstream once its shape | ||
| settles, or record why not. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| # [S] C consumers on the generated API | ||
|
|
||
| ## Goal | ||
|
|
||
| The C interop client (`test/interop/clients/c`) and the `doc/lib/c` samples use | ||
| the generated `moq-c` API and pass `just test interop --all` and the doc-sample | ||
| build. Nothing in the repository calls the hand-written ABI any more. | ||
|
|
||
| ## Plan | ||
|
|
||
| - Port the interop client first; it is the smallest real consumer and proves | ||
| the callback and dispatcher shape end to end. | ||
| - Rewrite `doc/lib/c` around the generated API, including a sample that runs | ||
| callbacks on the host's own loop through `moq_set_dispatcher`. | ||
|
|
||
| ## Required | ||
|
|
||
| - [moq-c package](/quest/m1/c/package.md) - the package these consumers link |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # [M] moq-c package from the generated C | ||
|
|
||
| ## Goal | ||
|
|
||
| The generated C ships as the `moq-c` package, version 0.8.0: a release archive | ||
| with the header, the moq-ffi staticlib, a CMake config exporting `moq::c`, and | ||
| `moq-c.pc`, built the same way `cpp/moq` builds the C++ package. It replaces the | ||
| hand-written crate's artifacts under the same names. | ||
|
|
||
| ## Plan | ||
|
|
||
| - Mirror `cpp/moq`: CMake runs `cargo build -p moq-ffi`, then the generator's C | ||
| backend, and installs the result; a probe test compiles and links from the | ||
| installed package through both `find_package(moq-c)` and pkg-config. | ||
| - The installed CMake config honors `CMAKE_INSTALL_LIBDIR`, so a `lib64` | ||
| distro gets a working `find_package`; the hand-written crate's config | ||
| hardcodes `<prefix>/lib`. | ||
| - `doc/index.md` says the C library ships static and shared; say what the | ||
| package actually ships. | ||
| - A release workflow and nightly/CI jobs follow the C++ package's, pinned to the | ||
| fork tag that carries the C backend. | ||
| - Every Cross-Package Sync row that names libmoq for moq-ffi changes points at | ||
| the generated package instead; update `AGENTS.md` in this quest. | ||
|
|
||
| ## Required | ||
|
|
||
| - [libmoq becomes moq-c](/quest/m1/moq-c.md) - the rename that frees the `moq-c` name and `moq::c` target this package takes over | ||
| - [C backend](/quest/m1/c/backend.md) - the generator output this packages |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| # [S] Retire the hand-written libmoq | ||
|
|
||
| ## Goal | ||
|
|
||
| The hand-written C crate is gone: its last release points users at the | ||
| generated `moq-c` 0.8.0, and the source, workflows, and docs that only served | ||
| it are deleted. `doc/setup/upgrade.md` tells C users how to move. | ||
|
|
||
| ## Plan | ||
|
|
||
| - Fold in any retirement step #4288 already planned for the renamed crate. | ||
| - Decide the parked m3 libmoq quests: delete each whose outcome the generated | ||
| API already provides, and say so in the PR. | ||
|
|
||
| ## Required | ||
|
|
||
| - [C consumers](/quest/m1/c/consumers.md) - nothing in the repository still calls the hand-written ABI |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -20,3 +20,7 @@ condition clears, move the quest to the milestone its work belongs in. | |
| - [#2893](/quest/m3/2893-video-validate-pipewire-dma-buf-capture-on-kde-hardware.md) - video: validate PipeWire DMA-BUF capture on KDE hardware | ||
| - [Embedded video](/quest/m3/video-embedded.md) - EGL import in the renderer, so moq-video presents on a Pi | ||
| - [Vision worker](/quest/m3/processor-vision.md) - a documented customer-run vision worker proves the processor contract | ||
| - [libmoq hidden opt-in](/quest/m3/libmoq-hidden.md) - `moq_origin_announced` takes a `hidden` flag so C callers can list `.`-named broadcasts | ||
| - [libmoq shutdown](/quest/m3/libmoq-shutdown.md) - OBS exits cleanly with the plugin loaded: a C ABI `moq_shutdown` stops the libmoq thread before the module is unloaded | ||
| - [libmoq CMake library](/quest/m3/libmoq-cmake-lib.md) - the in-tree CMake build links the `libmoq.a` cargo reports, not a hardcoded `target/<profile>` path | ||
| - [libmoq fetch](/quest/m3/libmoq-fetch.md) - libmoq gains an additive cached-group fetch entry point | ||
|
Comment on lines
+23
to
+26
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
These four quests are gated on an in-repository replacement, but AGENTS.md reference: quest/AGENTS.md:L14-L17 Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Keeping these in m3: the maintainer chose m3 explicitly after being shown that m3 is reserved for outside gates. Each quest's Plan says it is parked behind the generated C line and when it would come back. (Written by Opus 5.5) |
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The generated line is ordered before
moq-c.md, has no dependency on it, and promises to delete the same hand-written crate that the following quest renames. If the line completes in this order,moq-c.mdis left trying to rename a nonexistentrs/libmoq; if both proceed concurrently, they conflict over the package name and release artifacts. Either make the generated package depend on the rename and rank it afterward, or absorb and delete the superseded rename quest.AGENTS.md reference: quest/AGENTS.md:L63-L66
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed: the package quest now requires libmoq becomes moq-c, so the rename lands before the generated package takes over the name.
(Written by Opus 5.5)