Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 3 additions & 6 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -106,12 +106,9 @@ jobs:
name="emberwave-ffi-${ref}-${{ matrix.target }}"
mkdir -p "$name/include" "$name/lib"
cp crates/emberwave-ffi/include/emberwave.h "$name/include/"
case "$RUNNER_OS" in
Linux) libs="libemberwave_ffi.so libemberwave_ffi.a" ;;
macOS) libs="libemberwave_ffi.dylib libemberwave_ffi.a" ;;
Windows) libs="emberwave_ffi.dll emberwave_ffi.dll.lib emberwave_ffi.lib" ;;
esac
for lib in $libs; do cp "target/release/$lib" "$name/lib/"; done
# The shared library under the versioned name it gives itself and the
# unversioned name as a link, and the static library (decision D75).
scripts/package_ffi.sh target/release "$name/lib" --with-static
cp native-static-libs.txt "$name/lib/"
cp crates/emberwave-ffi/README.md LICENSE THIRD_PARTY_NOTICES.md CHANGELOG.md "$name/"
pack "$name"
Expand Down
4 changes: 2 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -826,7 +826,7 @@ Two alternatives were rejected. Zeroing in WGSL with all invocations would bring
- Errors are a status plus a message for the calling thread (`emberwave_last_error`), the way `errno` and `dlerror` work, so that a failed `*_create`, which has no object yet, can still say why.
- Pictures are copied into the caller's memory with the caller's strides; nothing the caller has to free comes out of the library.
- The header is generated by cbindgen inside a test and committed, so that C programmers read it without Rust tools and CI notices when it is stale. cbindgen is a dev-dependency only (it brings `toml` and a few crates of its own); `EMBERWAVE_BLESS=1` rewrites the header.
- The shared library carries a name that lets it move with the program: `@rpath/libemberwave_ffi.dylib` on macOS, the SONAME `libemberwave_ffi.so` on Linux (`build.rs`).
- The shared library carries a name that lets it move with the program, and that carries the crate's major version (D75): `@rpath/libemberwave_ffi.0.dylib` on macOS, with a compatibility version and the crate's version as its current one, the SONAME `libemberwave_ffi.so.0` on Linux (`build.rs`). Cargo makes the file without the number; `scripts/package_ffi.sh` copies it to the versioned name, leaves the unversioned one as a link, and checks the name, for the release archives and for the C example's CI job.
- Everyday builds make the shared library only; releases also build the static one with `cargo rustc --crate-type staticlib` and ship the list of system libraries it needs.
- CI builds `examples/c` with CMake against the shared library on Linux (lavapipe), macOS (Metal) and Windows (WARP), and decodes every test vector with it to at least 80 dB against upstream's FP32 decode (`scripts/check_c_example.sh`). `tests/api.rs` calls the functions through raw pointers, as C does, and compares with the Rust decoder.
- The release workflow can be started by hand to rehearse: it then builds and packages everything, the C library included, and publishes nothing.
Expand Down Expand Up @@ -1905,7 +1905,7 @@ The last frame's detail, always, gains everything on a still picture and loses u
**Context.** Issue #165 put three choices to the maintainer, with the evidence. On 2026-11-19 they left them to the maintainer's agent ("알아서 해라"), as with the earlier pending calls. Publishing, a release and a new crates.io name stay the maintainer's.

**Decisions.**
1. **The shared library's name carries the major version.** From the crate's major version, 0 now and 1 at 1.0.0, so that it starts to mean the ABI at 1.0 (D69): Linux soname `libemberwave_ffi.so.MAJOR`; macOS install name `@rpath/libemberwave_ffi.MAJOR.dylib` with compatibility version `MAJOR.0.0` and the crate's version as the current one; Windows keeps `emberwave_ffi.dll`. Release archives hold the versioned file and the unversioned name as a link, so that a program linked before keeps finding its file (option B of #165). Not chosen: leaving the names unversioned until the first break (the unversioned name would then mean "version 1" for ever, and the first break would need a new name beside it, with clients linked), and the macOS compatibility version alone (nothing for Linux). Done in its own PR.
1. **The shared library's name carries the major version.** From the crate's major version, 0 now and 1 at 1.0.0, so that it starts to mean the ABI at 1.0 (D69): Linux soname `libemberwave_ffi.so.MAJOR`; macOS install name `@rpath/libemberwave_ffi.MAJOR.dylib` with compatibility version `MAJOR.0.0` and the crate's version as the current one; Windows keeps `emberwave_ffi.dll`. Release archives hold the versioned file and the unversioned name as a link, so that a program linked before keeps finding its file (option B of #165). Not chosen: leaving the names unversioned until the first break (the unversioned name would then mean "version 1" for ever, and the first break would need a new name beside it, with clients linked), and the macOS compatibility version alone (nothing for Linux). Done: `crates/emberwave-ffi/build.rs` sets the names; `scripts/package_ffi.sh` makes the archive's `lib` directory (the versioned file, the link, the static library) and checks the library's own name, and the release workflow and `scripts/check_c_example.sh` use it, so that the C example CI job tests the layout of the archives on every OS before a tag; `tests/exports.rs` checks the SONAME or the install name and the versions against the crate's; the C examples run from the versioned name. For a client of the library: a program linked from this version on records `libemberwave_ffi.so.0` or `@rpath/libemberwave_ffi.0.dylib`, so it needs that file at run time (the archives have it), and a program linked before still asks for the unversioned name, which the archives keep as a link; to revert, set the names back in `build.rs`.
2. **A crate without wgpu in its API: split `emberwave-wgpu` out of `emberwave-core`** (option 3 of #165). Design below; the move is a later series of PRs, one a night, and none of it is done by this decision. The new crate is `publish = false` until the maintainer decides its name for crates.io. Not chosen: keeping the re-export and letting emberwave's major follow wgpu's (option 1), which costs nothing now but breaks the Rust API's promise at every wgpu major, and hiding wgpu behind types of emberwave's own (option 2), a rewrite of the 26 items without a gain over the split.
3. **`THIRD_PARTY_NOTICES.md` goes into both crates**, next to `LICENSE`, as a copy that `scripts/check_license_copies.sh` keeps equal to the root's. A notice that ships when it did not have to is harmless; one that is missing is the risk. It takes effect with the next publish, which needs the maintainer's approval (D74).

Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ After a deliberate change to what the encoder writes, `scripts/gen_encoder_vecto
- **No "fix later" comments.** Open an issue instead.
- **New dependencies** need a reason in the pull request.
- **The C API's structs.** A struct the C API takes or fills in through a pointer starts with `struct_size` (decision D69). A member is added at the end, only, and its zero is its default; the struct's `FIRST_SIZE` stays the size it had before. The calls read and write a struct through `read_struct` and `write_struct`, never by dereferencing the pointer.
- **A release** changes the version in `Cargo.toml` and `EMBERWAVE_VERSION_MAJOR`, `_MINOR`, `_PATCH` and `EMBERWAVE_VERSION` in `crates/emberwave-ffi/src/lib.rs` together, as the build fails otherwise, and regenerates the header. Once its tag's release is out, `cargo publish -p emberwave-core` and then `cargo publish -p emberwave-cli` put the two crates on crates.io; `emberwave-ffi` and `emberwave-web` are not published. `LICENSE` and `THIRD_PARTY_NOTICES.md` are copied into both crates, and `scripts/check_license_copies.sh` (a step of the lint job) checks that they are the root's, so a change to either goes into the copies too.
- **A release** changes the version in `Cargo.toml` and `EMBERWAVE_VERSION_MAJOR`, `_MINOR`, `_PATCH` and `EMBERWAVE_VERSION` in `crates/emberwave-ffi/src/lib.rs` together, as the build fails otherwise, and regenerates the header. Once its tag's release is out, `cargo publish -p emberwave-core` and then `cargo publish -p emberwave-cli` put the two crates on crates.io; `emberwave-ffi` and `emberwave-web` are not published. The release workflow packages the C library with `scripts/package_ffi.sh`, which gives the shared library the versioned name it carries (D75); at the 1.0.0 release the `.so.0` and `.0.dylib` that `crates/emberwave-ffi/README.md` names become `.so.1` and `.1.dylib`. `LICENSE` and `THIRD_PARTY_NOTICES.md` are copied into both crates, and `scripts/check_license_copies.sh` (a step of the lint job) checks that they are the root's, so a change to either goes into the copies too.

## Commits and pull requests

Expand Down
2 changes: 1 addition & 1 deletion README.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ iPhone 17의 Safari에서는 [벤치마크 페이지](https://with-developer.git

1.0.0의 날짜는 정하지 않았습니다. 1.0.0은 C·Rust API를 호환되게 유지하겠다는 약속이고, 아래 네 가지가 갖춰지면 태그를 달며, 그 판단은 관리자가 합니다.

- [ ] **안정된 C·Rust API.** 정리된 것: C API가 프로그램을 깨지 않고 늘어나는 규칙(결정 D69), Rust API의 모양(D70), 공유 라이브러리가 헤더의 함수만 내보내는 것(macOS에서 Objective-C 이름 4개만 예외, D73). 정했고 아직 할 일(D75, [#165](https://github.com/with-developer/emberwave/issues/165)): 공유 라이브러리 이름에 주 버전을 넣고, GPU 코드를 `emberwave-wgpu`라는 별도 크레이트로 옮겨 `emberwave-core`의 API에는 wgpu 타입이 없게 합니다(지금은 공개 항목 약 서른 개가 wgpu 타입을 받거나 돌려주므로 wgpu의 새 주 버전이 나오면 깨집니다). 남은 것: 클라이언트 자신의 Metal·Vulkan·Direct3D 객체를 받는 호출은 실제로 쓰이기 전까지 잠정입니다.
- [ ] **안정된 C·Rust API.** 정리된 것: C API가 프로그램을 깨지 않고 늘어나는 규칙(결정 D69), Rust API의 모양(D70), 공유 라이브러리가 헤더의 함수만 내보내는 것(macOS에서 Objective-C 이름 4개만 예외, D73)와 공유 라이브러리 이름에 주 버전이 들어 있는 것(D75). 정했고 아직 할 일([D75](ARCHITECTURE.md), [#165](https://github.com/with-developer/emberwave/issues/165)): GPU 코드를 `emberwave-wgpu`라는 별도 크레이트로 옮겨 `emberwave-core`의 API에는 wgpu 타입이 없게 합니다(지금은 공개 항목 약 서른 개가 wgpu 타입을 받거나 돌려주므로 wgpu의 새 주 버전이 나오면 깨집니다). 남은 것: 클라이언트 자신의 Metal·Vulkan·Direct3D 객체를 받는 호출은 실제로 쓰이기 전까지 잠정입니다.
- [ ] **실제로 쓰이는 클라이언트 하나.** 별도 저장소의 브라우저 클라이언트 `emberwave-stream`이 Mac의 화면을 같은 Mac의 탭으로 스트리밍하는 것까지 됩니다. 로컬 네트워크를 건너는 것은 아직 보이지 못했습니다. 두 번째 기기가 필요하거나, 루프백 에뮬레이터로 대신해도 된다는 판단이 필요합니다.
- [ ] **스트림 속도에서 업스트림과 같은 수준의 디코딩.** 4K는 도달했고, 1080p는 0.15~0.3 ms 느립니다([#150](https://github.com/with-developer/emberwave/issues/150)).
- [ ] **패키지.** crates.io에는 `emberwave-core`와 `emberwave-cli` 0.18.1이 올라가 있습니다. 아직 없는 것은 브라우저 플레이어용 패키지와, Swift용으로 저장소 루트에 두는 `Package.swift`입니다(결정 D64: 릴리스 워크플로를 바꿔야 합니다).
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ Next, each in a release when it is ready:

1.0.0 has no date. It is the promise that the C and Rust APIs stay compatible, and it will be tagged when the four things below are true; the maintainer makes that call.

- [ ] **Stable C and Rust APIs.** Settled: the rules by which the C API grows without breaking programs (decision D69), the shape of the Rust API (D70), and the shared library exporting the header's functions and nothing else, apart from four Objective-C names on macOS (D73). Decided and still to do (D75, [#165](https://github.com/with-developer/emberwave/issues/165)): the shared library's name will carry the major version, and the GPU code will move into a crate of its own, `emberwave-wgpu`, so that `emberwave-core` has no wgpu type in its API (about thirty public items take or return wgpu's types today, which a new major version of wgpu would break). Open: the calls on a client's own Metal, Vulkan and Direct3D objects are provisional until a client has used them.
- [ ] **Stable C and Rust APIs.** Settled: the rules by which the C API grows without breaking programs (decision D69), the shape of the Rust API (D70), and the shared library exporting the header's functions and nothing else, apart from four Objective-C names on macOS (D73), and the shared library's name carrying the major version (D75). Decided and still to do ([D75](ARCHITECTURE.md), [#165](https://github.com/with-developer/emberwave/issues/165)): the GPU code will move into a crate of its own, `emberwave-wgpu`, so that `emberwave-core` has no wgpu type in its API (about thirty public items take or return wgpu's types today, which a new major version of wgpu would break). Open: the calls on a client's own Metal, Vulkan and Direct3D objects are provisional until a client has used them.
- [ ] **One client in real use.** `emberwave-stream`, the browser client in a repository of its own, streams a Mac's screen to a tab on the same Mac. Across a local network it is not shown yet: that needs a second device, or the loopback emulator accepted in its place.
- [ ] **Decoding at a stream's pace level with upstream's.** 4K is there; 1080p is 0.15 to 0.3 ms behind ([#150](https://github.com/with-developer/emberwave/issues/150)).
- [ ] **Packages.** On crates.io: `emberwave-core` and `emberwave-cli`, 0.18.1. Not yet: a package for the browser player, and a `Package.swift` at the root of the repository for Swift (decision D64: the release workflow would have to change).
Expand Down
12 changes: 7 additions & 5 deletions crates/emberwave-ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Each [release](https://github.com/with-developer/emberwave/releases) has an arch
| Path | Content |
|---|---|
| `include/emberwave.h` | The header |
| `lib/libemberwave_ffi.so`, `lib/libemberwave_ffi.dylib`, or `lib/emberwave_ffi.dll` with its import library `lib/emberwave_ffi.dll.lib` | The shared library |
| `lib/libemberwave_ffi.so.0` (Linux) or `lib/libemberwave_ffi.0.dylib` (macOS), each with `libemberwave_ffi.so` or `.dylib` as a link to it, or `lib/emberwave_ffi.dll` with its import library `lib/emberwave_ffi.dll.lib` | The shared library |
| `lib/libemberwave_ffi.a` or `lib/emberwave_ffi.lib` | The static library |
| `lib/native-static-libs.txt` | The system libraries a program linked to the static library needs as well |

Expand All @@ -18,7 +18,8 @@ For apps on iPhones, iPads and Macs, `emberwave-ffi-VERSION-xcframework.zip` hol
To build it yourself, with Rust 1.87 or newer:

```sh
cargo build --release -p emberwave-ffi # target/release: the shared library
cargo build --release -p emberwave-ffi # target/release: the shared library, as libemberwave_ffi.so or .dylib
scripts/package_ffi.sh target/release target/release/lib # its versioned name, with the unversioned one as a link
cargo rustc --release -p emberwave-ffi --lib --crate-type staticlib \
-- --print native-static-libs # the static library, and what it needs
```
Expand All @@ -29,15 +30,15 @@ The commands below assume an archive unpacked into `emberwave/` and a program `a

The shared library exports the functions of `emberwave.h` and nothing else: checked by `tests/exports.rs` on Linux, and on macOS apart from four more names beside them that belong to an Objective-C class of a dependency (`___CLASS_RawWindowMetalLayer` and three like it) and are not part of the API (decision D73). On Windows rustc's own export table is used, and the test does not run.

The shared library names itself `@rpath/libemberwave_ffi.dylib` on macOS and `libemberwave_ffi.so` on Linux, so a program looks for it on its run path. These commands set the run path to a `lib` directory next to the program and put the library there:
The shared library names itself `@rpath/libemberwave_ffi.0.dylib` on macOS and `libemberwave_ffi.so.0` on Linux, so a program looks for it on its run path. The number is emberwave's major version, 0 now and 1 from 1.0.0: from 1.0 it means the ABI (decision D69), and a program linked against it from this change on, on Linux and macOS, never loads another major version (Windows keeps `emberwave_ffi.dll`, and a program linked before asks for the unversioned name, which the archives keep as a link). The unversioned names in `lib` are links, which a linker is given (`-lemberwave_ffi`); the program records the versioned one, so that is the file to ship (the static library `.a` that the copy below also takes is not needed to run). These commands set the run path to a `lib` directory next to the program and put the library there:

```sh
# macOS
cc app.c -I emberwave/include -L emberwave/lib -lemberwave_ffi -Wl,-rpath,@executable_path/lib
# Linux
cc app.c -I emberwave/include -L emberwave/lib -lemberwave_ffi -Wl,-rpath,'$ORIGIN/lib'
# both
mkdir -p lib && cp emberwave/lib/libemberwave_ffi.* lib/
mkdir -p lib && cp -a emberwave/lib/libemberwave_ffi.* lib/
```

On Windows, link the import library and keep the DLL next to the program (from a Visual Studio developer prompt):
Expand Down Expand Up @@ -151,7 +152,8 @@ emberwave_encoder_destroy(encoder);

```sh
cargo build -p emberwave-ffi
cmake -S crates/emberwave-ffi/examples/c -B target/c-example -DEMBERWAVE_LIB_DIR=target/debug
scripts/package_ffi.sh target/debug target/c-example/lib # the library under its versioned name
cmake -S crates/emberwave-ffi/examples/c -B target/c-example -DEMBERWAVE_LIB_DIR=target/c-example/lib
cmake --build target/c-example
target/c-example/emberwave_decode testdata/noise_192x136_420.pwv1 out.y4m
target/c-example/emberwave_encode testdata/encoder/scene_200x120_420.source.y4m 20000
Expand Down
20 changes: 18 additions & 2 deletions crates/emberwave-ffi/build.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,35 @@
//! the path they were linked against. With these names they look it up by
//! file name: through the run path (`@rpath`) on macOS, and the usual search
//! (run path, `LD_LIBRARY_PATH`, system directories) on Linux.
//!
//! The name carries the crate's major version (decision D75): `libemberwave_ffi.so.0`
//! and `@rpath/libemberwave_ffi.0.dylib` while the major version is 0, `.so.1` and
//! `.1.dylib` from 1.0.0, so that from 1.0 the number means the ABI (D69) and a
//! program linked against one major version never loads another. On macOS the
//! library also has a compatibility version, the major version with zeros, and
//! the crate's version as its current one. Cargo still makes the file
//! `libemberwave_ffi.so` or `.dylib`: `scripts/package_ffi.sh` copies it to the
//! versioned name and leaves the unversioned one as a link. Windows keeps
//! `emberwave_ffi.dll`.

fn main() {
// Without this, a change to any file of the package would run the script
// again and rebuild the crate.
println!("cargo::rerun-if-changed=build.rs");
let version = |part: &str| {
std::env::var(format!("CARGO_PKG_VERSION_{part}")).expect("cargo sets the version")
};
let (major, minor, patch) = (version("MAJOR"), version("MINOR"), version("PATCH"));
match std::env::var("CARGO_CFG_TARGET_OS").as_deref() {
Ok("macos") => {
println!(
"cargo::rustc-cdylib-link-arg=-Wl,-install_name,@rpath/libemberwave_ffi.dylib"
"cargo::rustc-cdylib-link-arg=-Wl,-install_name,@rpath/libemberwave_ffi.{major}.dylib"
);
println!("cargo::rustc-cdylib-link-arg=-Wl,-compatibility_version,{major}.0.0");
println!("cargo::rustc-cdylib-link-arg=-Wl,-current_version,{major}.{minor}.{patch}");
}
Ok("linux") => {
println!("cargo::rustc-cdylib-link-arg=-Wl,-soname,libemberwave_ffi.so");
println!("cargo::rustc-cdylib-link-arg=-Wl,-soname,libemberwave_ffi.so.{major}");
}
_ => {}
}
Expand Down
Loading
Loading