Repository navigation
Description
Two choices of the maintainer's, before 1.0.0 makes them hard to undo. Neither is decided; nothing is changed by this issue.
1. The shared library's name
What exists today
- The name is set in
crates/emberwave-ffi/build.rs: macOS install name@rpath/libemberwave_ffi.dylib(line 15), Linux sonamelibemberwave_ffi.so(line 19), Windowsemberwave_ffi.dllwith the import libraryemberwave_ffi.dll.lib. None has a version. - Release archives hold
lib/libemberwave_ffi.so(Linux),lib/libemberwave_ffi.dylib(macOS) oremberwave_ffi.dll,.dll.liband.lib(Windows), and the static.aor.lib(.github/workflows/release.yml, lines 110 to 112). The XCFramework holds a static library: it has no name to version. - A C client that links with
-lemberwave_ffirecords the soname or install name in its executable and looks for that file when it starts. The C examples' CMake file names the unversioned files (examples/c/CMakeLists.txt, lines 25 to 32). - Who links it today: our C examples, the Swift example and the benchmark app (static XCFramework, not affected), and
emberwave-stream(a Rust dependency, not the C library). No client outside the repository is known. - What a version in the name changes for a client: programs linked after it record
libemberwave_ffi.so.1(Linux) and need that file; programs linked before it still ask forlibemberwave_ffi.so, which then has to stay beside it as a link, or they fail to start. macOS is the same with the install name. D69 left this for 1.0, "when the major version starts to mean the ABI".
Options
- A. Keep the names unversioned until the first breaking change. Nothing to do now. The unversioned name then means "version 1" for good, and the first breaking release needs a new name beside it. Cost: later, with clients linked; one more thing to remember.
- B. Version it now (Linux
libemberwave_ffi.so.1, macOS@rpath/libemberwave_ffi.1.dylibwith a compatibility version), keeplibemberwave_ffi.soand.dylibas links in the archives. Cost: the build script, the archive layout (links in tar archives; zip archives for Windows cannot hold them, so Windows stays as it is or gets a-1name), the CMake file and the README. A day's work. Every later breaking release gets a new number and clients stay safe. - C. Only the macOS compatibility and current versions, names unchanged. Smallest: dyld can refuse a library that is too old. Does nothing for Linux.
Reversibility, who is affected
Before 1.0, any of them is cheap: nobody outside the repository links the library. After clients link it, a name cannot be taken back without breaking them (the links keep old programs working, new names cannot be removed). Affected: C and C++ programs that link the shared library on Linux, macOS and Windows; not Swift apps (static XCFramework), not Rust users, not the CLI.
Recommendation
B for Linux and macOS, done before 1.0.0-rc.1 so that the release candidate is what clients link against. Windows keeps its names.
2. How wgpu shows in the Rust API
What exists today
emberwave-core re-exports wgpu (crates/emberwave-core/src/lib.rs:23, pub use wgpu) and 25 public fields, functions and constants take or return its types (found by scanning the public signatures; the five fields of gpu/pipelines.rs are in a private module and are not counted). Beside them, the three methods of the SubmissionHooks trait and the variants of TexturePicture take wgpu's command encoder, queue and texture views, so "about thirty", as D70 says, is the honest count:
- Setup (3): the fields
backendsandpower_preferenceofGpuOptions(gpu/context.rs:22, 24), andparse_backends(:94). - A context from the client's wgpu objects (3):
from_adapter(:215),device_descriptor(:230),from_device(:289). - Reaching wgpu's objects (5):
adapter_info,device,queueof the context (:371, 376, 381);deviceof the decoder (gpu/decoder.rs:787) and of the encoder (gpu/encoder.rs:584). - Decoding into the client's textures and buffers (14):
record_rgb,rgba_buffer,record_rgb_to_texture,decode_assembled_to_texture,submit_assembled_to_texture,submit_assembled_to_texture_with,create_texture,record_to_plane_textures,decode_assembled_to_plane_textures,submit_assembled_to_plane_textures,submit_assembled_to_plane_textures_with,create_plane_texture(gpu/decoder.rs:514to:742); the constantsTEXTURE_FORMATSandPLANE_FORMAT(:306, 314). - Not in the C API:
emberwave-ffihas no public item with a wgpu type; the C functions use raw pointers and the client's own Metal, Vulkan and Direct3D objects. - A Rust client that only decodes or encodes through byte buffers, or uses the CLI or the C API, uses none of these. One that decodes into its own wgpu textures or shares its device uses 10 to 20 of them.
- wgpu published 30.0.0 on 2026-07-01 and 30.0.2 on 2026-11-12; a new major version of wgpu changes these types. D70 noted this and left it for 1.0.
Options
- 1. Keep the re-export and let emberwave's major version follow wgpu's. Nothing to build. Cost: every wgpu major version forces an emberwave major version, so "1.0" would not promise stability of the Rust API for long. Fits a library whose users are wgpu applications.
- 2. Hide wgpu behind emberwave's own types (its own texture format, backends and power preference; the client's device and queue through one
unsafeinterop module). Cost: wrapper types, losing the direct hand-over of a wgpu texture, a rewrite of those items and their tests, and emberwave-stream's host and the browser player to change. - 3. Split a crate:
emberwave-corekeeps the parser, the assembler, the CPU decoder and encoder, the byte-buffer GPU calls, and has no wgpu type in its public API; a new crate (for exampleemberwave-wgpu) holds the wgpu-typed items and follows wgpu's majors. This is D70's second answer. Cost: a new crate to publish and maintain, a restructure of the GPU module, the CLI, the web crate and emberwave-stream to follow; a new infrastructure item that needs the maintainer's approval (new crates.io name).
Reversibility, who is affected
- Before 1.0 all three are possible; after 1.0, 2 and 3 are breaking changes, so they would be 2.0.
- Affected: Rust users of
emberwave-core's GPU API (crates.io has 0.18.1; no outside user is known) andemberwave-stream(ours). Not affected: C and Swift users, the CLI, the browser player's users.
Recommendation
3, because the core is the part worth promising stability for, and wgpu will bump its major again. Done before 1.0.0, in a 0.19 or 0.20 step so that the split is tested by emberwave-stream before it is frozen. If the cost looks too high, 1 is acceptable only with a plain statement in the README that emberwave's major follows wgpu's.
Activity
with-developer commentedon Nov 19, 2026
Decided on 2026-11-19: the maintainer left the three choices to their agent. The record is D75 in ARCHITECTURE.md (PR follows this comment); the outcome:
libemberwave_ffi.so.MAJOR, macOS@rpath/libemberwave_ffi.MAJOR.dylibwith a compatibility version, Windows unchanged; release archives hold the versioned file and the unversioned name as a link. MAJOR is 0 now and 1 at 1.0.0, so the name starts to mean the ABI at 1.0. Its own PR follows.emberwave-wgpuout ofemberwave-core(option 3). The data: the core'sgpufeature is already a boundary (10,325 lines of GPU code against 6,934 of parser, CPU codecs and colour, which have nothing fromgpu); everything with a wgpu type is inside it (25 items and the re-export, plus the hooks trait andTexturePicture); the GPU code uses sixpub(crate)items of the core, which become#[doc(hidden)] pub;emberwave-cli(26 lines),emberwave-ffi(138; the C API does not change),emberwave-web(24) and emberwave-stream's host (four imports, no wgpu types) follow; about 14,000 lines move, mechanically. What it costs: a hidden surface between two crates of one repository, and a publishedemberwave-cliwill needemberwave-wgpupublished first, which is a new crates.io name and stays the maintainer's call; the new crate ispublish = falseuntil then. The order of the work is in D75: open the six items, one PR for the move and the dependents, docs, emberwave-stream, the release workflow's order. Nothing moves yet. Not chosen: option 1 (free now, but a Rust API promise that breaks at every wgpu major) and option 2 (a rewrite of the 26 items without a gain over the split).THIRD_PARTY_NOTICES.mdgoes into both crates next toLICENSE, kept equal to the root's byscripts/check_license_copies.shin CI. It reaches crates.io with the next publish, which needs the maintainer's approval.with-developer commentedon Nov 19, 2026
Decision 1 is in main (#171): the shared library's name carries the crate's major version (Linux
libemberwave_ffi.so.0, macOS@rpath/libemberwave_ffi.0.dylibwith a compatibility version),scripts/package_ffi.shmakes the archives'libdirectory with the unversioned name as a link and checks the library's own name, the C example job tests that layout on Linux, macOS and Windows on every PR, and a test compares the names and versions with the crate's. Decision 3 is in main (#170): the notices are copied into both crates and kept equal by CI. Decision 2 (theemberwave-wgpusplit) is designed in D75; the work is one PR a night, first the six core items. Nothing was published or released.