From c1439d39031271eed8812a0ef0c69e31ceed9810 Mon Sep 17 00:00:00 2001 From: harry Date: Thu, 19 Nov 2026 18:09:42 +0900 Subject: [PATCH 1/4] feat(ffi): the shared library's name carries the major version From 1.0 the number in a shared library's name should mean its ABI, so that a program linked against one major version never loads another (D69, D75). The library names itself by the crate's major version, 0 now and 1 from 1.0.0: the SONAME libemberwave_ffi.so.0 on Linux, the install name @rpath/libemberwave_ffi.0.dylib on macOS with a compatibility version of 0.0.0 and the crate's version as its current one. Windows keeps emberwave_ffi.dll. Cargo still makes libemberwave_ffi.so and .dylib. scripts/package_ffi.sh copies the file to its versioned name, leaves the unversioned one as a link, adds the static library for a release, and checks the library's own name with readelf or otool. The release workflow and scripts/check_c_example.sh use it, so that the C example job tests the layout of the archives on every OS before a tag, and the C examples run from the versioned name. A test next to the export test reads the SONAME or the install name and the versions and compares them with the crate's. For a client: a program linked from this version on records the versioned name and needs that file at run time, which the archives hold; a program linked before asks for the unversioned name, which they keep as a link. Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42 --- .github/workflows/release.yml | 9 +-- crates/emberwave-ffi/README.md | 9 +-- crates/emberwave-ffi/build.rs | 20 ++++++- crates/emberwave-ffi/tests/exports.rs | 83 ++++++++++++++++++++++++++- scripts/check_c_example.sh | 7 ++- scripts/package_ffi.sh | 62 ++++++++++++++++++++ 6 files changed, 176 insertions(+), 14 deletions(-) create mode 100755 scripts/package_ffi.sh diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9755033..bcbc667 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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" diff --git a/crates/emberwave-ffi/README.md b/crates/emberwave-ffi/README.md index 71ace0f..f863231 100644 --- a/crates/emberwave-ffi/README.md +++ b/crates/emberwave-ffi/README.md @@ -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 | @@ -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 lib # gives it 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 ``` @@ -29,7 +30,7 @@ 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 one major version never loads another. 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. These commands set the run path to a `lib` directory next to the program and put the library there: ```sh # macOS @@ -37,7 +38,7 @@ cc app.c -I emberwave/include -L emberwave/lib -lemberwave_ffi -Wl,-rpath,@execu # 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): diff --git a/crates/emberwave-ffi/build.rs b/crates/emberwave-ffi/build.rs index f837c54..e9e0043 100644 --- a/crates/emberwave-ffi/build.rs +++ b/crates/emberwave-ffi/build.rs @@ -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}"); } _ => {} } diff --git a/crates/emberwave-ffi/tests/exports.rs b/crates/emberwave-ffi/tests/exports.rs index ac3d374..af7ffc6 100644 --- a/crates/emberwave-ffi/tests/exports.rs +++ b/crates/emberwave-ffi/tests/exports.rs @@ -1,4 +1,5 @@ -//! The shared library exports the functions of the C header and nothing else. +//! The shared library exports the functions of the C header and nothing else, and +//! names itself by the crate's major version. //! //! The header, `include/emberwave.h`, is the list: a function that it declares //! has to be exported, and a name that is exported without being declared there @@ -224,3 +225,83 @@ fn the_library_exports_the_header_s_functions_and_nothing_else() { library.display() ); } + +/// The name the library gives itself, and on macOS its compatibility and current +/// versions, as the platform's tools print them: `readelf -d` for the SONAME on +/// Linux, `otool -l` for the install name and the versions on macOS. +fn own_name(library: &PathBuf) -> (String, Option<(String, String)>) { + if cfg!(target_os = "macos") { + let output = Command::new("otool") + .arg("-l") + .arg(library) + .output() + .expect("otool runs"); + assert!(output.status.success(), "otool failed"); + let text = String::from_utf8(output.stdout).expect("otool prints UTF-8"); + // The LC_ID_DYLIB command, up to the next one. + let block = text + .split("cmd LC_ID_DYLIB") + .nth(1) + .expect("the library has an install name") + .split("Load command") + .next() + .expect("the command ends"); + let field = |label: &str, after: &str| { + block + .lines() + .map(str::trim) + .find_map(|line| line.strip_prefix(label)) + .map(|rest| { + rest.trim() + .split(after) + .next() + .expect("a value") + .trim() + .to_string() + }) + .unwrap_or_else(|| panic!("no {label} in {block}")) + }; + let name = field("name ", " (offset"); + ( + name, + Some(( + field("compatibility version ", " "), + field("current version ", " "), + )), + ) + } else { + let output = Command::new("readelf") + .arg("-d") + .arg(library) + .output() + .expect("readelf runs"); + assert!(output.status.success(), "readelf failed"); + let text = String::from_utf8(output.stdout).expect("readelf prints UTF-8"); + let name = text + .lines() + .find_map(|line| line.split("Library soname: [").nth(1)) + .and_then(|rest| rest.split(']').next()) + .expect("the library has a SONAME") + .to_string(); + (name, None) + } +} + +#[test] +fn the_library_names_itself_by_its_major_version() { + let major = env!("CARGO_PKG_VERSION_MAJOR"); + let version = format!( + "{major}.{}.{}", + env!("CARGO_PKG_VERSION_MINOR"), + env!("CARGO_PKG_VERSION_PATCH") + ); + let (name, versions) = own_name(&library()); + if cfg!(target_os = "macos") { + assert_eq!(name, format!("@rpath/libemberwave_ffi.{major}.dylib")); + let (compatibility, current) = versions.expect("macOS libraries have versions"); + assert_eq!(compatibility, format!("{major}.0.0")); + assert_eq!(current, version); + } else { + assert_eq!(name, format!("libemberwave_ffi.so.{major}")); + } +} diff --git a/scripts/check_c_example.sh b/scripts/check_c_example.sh index cfe6533..ac36a1a 100755 --- a/scripts/check_c_example.sh +++ b/scripts/check_c_example.sh @@ -22,8 +22,13 @@ cd "$(dirname "$0")/.." CARGO_OUT=${1:-target/debug} BUILD=target/c-example +# The library as a release archive has it, under its versioned name, which is +# the one a program linked against it looks for (decision D75); the script also +# checks that the library's own name is that one. +scripts/package_ffi.sh "$CARGO_OUT" "$BUILD/lib" + cmake -S crates/emberwave-ffi/examples/c -B "$BUILD" \ - -DEMBERWAVE_LIB_DIR="$CARGO_OUT" -DCMAKE_BUILD_TYPE=Debug + -DEMBERWAVE_LIB_DIR="$BUILD/lib" -DCMAKE_BUILD_TYPE=Debug cmake --build "$BUILD" --config Debug # Single-configuration generators put the programs in the build directory, diff --git a/scripts/package_ffi.sh b/scripts/package_ffi.sh new file mode 100755 index 0000000..4ddfd2c --- /dev/null +++ b/scripts/package_ffi.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# Puts the C library into a `lib` directory as a release archive has it, and +# checks that its name is the one the library gives itself (decision D75). +# +# Cargo makes `libemberwave_ffi.so` or `libemberwave_ffi.dylib`. The library +# names itself by the crate's major version (`crates/emberwave-ffi/build.rs`): +# the SONAME `libemberwave_ffi.so.0` on Linux, the install name +# `@rpath/libemberwave_ffi.0.dylib` on macOS, `.1` from 1.0.0. A program linked +# against it records that name and looks for that file, so the library is copied +# to it and the unversioned name stays beside it as a link, which is what a +# linker is given (`-lemberwave_ffi`). Windows keeps `emberwave_ffi.dll`. +# +# Usage: scripts/package_ffi.sh SRC DEST [--with-static] +# +# SRC where cargo put the library: target/release, target/debug +# DEST the directory to fill, made if it is not there +# --with-static also copy the static library (`libemberwave_ffi.a`, or +# `emberwave_ffi.lib` on Windows), which a release builds apart +# +# Needs readelf on Linux and otool on macOS for the check. +set -euo pipefail + +cd "$(dirname "$0")/.." +SRC=${1:?usage: scripts/package_ffi.sh SRC DEST [--with-static]} +DEST=${2:?usage: scripts/package_ffi.sh SRC DEST [--with-static]} +WITH_STATIC=${3:-} + +# The workspace's version, which the crates take: its first number is the major. +version=$(sed -n '/^\[workspace.package\]/,/^\[/{s/^version = "\([0-9]*\)\..*/\1/p;}' Cargo.toml) +major=${version:?no version in Cargo.toml} + +mkdir -p "$DEST" +case "$(uname -s)" in + Linux) + versioned=libemberwave_ffi.so.$major + cp "$SRC/libemberwave_ffi.so" "$DEST/$versioned" + ln -sf "$versioned" "$DEST/libemberwave_ffi.so" + [ -z "$WITH_STATIC" ] || cp "$SRC/libemberwave_ffi.a" "$DEST/" + soname=$(readelf -d "$DEST/$versioned" | sed -n 's/.*Library soname: \[\(.*\)\]/\1/p') + [ "$soname" = "$versioned" ] || { + echo "the library's SONAME is '$soname', not $versioned" >&2 + exit 1 + } + ;; + Darwin) + versioned=libemberwave_ffi.$major.dylib + cp "$SRC/libemberwave_ffi.dylib" "$DEST/$versioned" + ln -sf "$versioned" "$DEST/libemberwave_ffi.dylib" + [ -z "$WITH_STATIC" ] || cp "$SRC/libemberwave_ffi.a" "$DEST/" + name=$(otool -D "$DEST/$versioned" | tail -n 1) + [ "$name" = "@rpath/$versioned" ] || { + echo "the library's install name is '$name', not @rpath/$versioned" >&2 + exit 1 + } + ;; + *) + # Windows (Git Bash): the names do not change. + cp "$SRC/emberwave_ffi.dll" "$SRC/emberwave_ffi.dll.lib" "$DEST/" + [ -z "$WITH_STATIC" ] || cp "$SRC/emberwave_ffi.lib" "$DEST/" + ;; +esac +echo "$DEST: $(ls "$DEST" | tr '\n' ' ')" From 88c0fc9ba9b84391f7677281c0a94270a6cb0aea Mon Sep 17 00:00:00 2001 From: harry Date: Thu, 19 Nov 2026 18:19:23 +0900 Subject: [PATCH 2/4] docs: the versioned library name, in D75, ARCHITECTURE, CONTRIBUTING and the README D75 says what was done for decision 1 and what a client of the library sees; ARCHITECTURE's note on the library's name, CONTRIBUTING's release step and the README's 1.0 checklist follow. Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42 --- ARCHITECTURE.md | 4 ++-- CONTRIBUTING.md | 2 +- README.ko.md | 2 +- README.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index fb93612..1ad8f50 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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. @@ -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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a2c979..11169b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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). `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 diff --git a/README.ko.md b/README.ko.md index 8d4c495..30d0e72 100644 --- a/README.ko.md +++ b/README.ko.md @@ -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, [#165](https://github.com/with-developer/emberwave/issues/165)): 공유 라이브러리 이름에는 이제 주 버전이 들어 있고(D75), 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: 릴리스 워크플로를 바꿔야 합니다). diff --git a/README.md b/README.md index 8573849..fb950f1 100644 --- a/README.md +++ b/README.md @@ -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). Decided and still to do (D75, [#165](https://github.com/with-developer/emberwave/issues/165)): the shared library's name carries the major version now (D75), 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. - [ ] **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). From 4ff4d75df7db6ace50985bde0315a7841713d8cb Mon Sep 17 00:00:00 2001 From: harry Date: Thu, 19 Nov 2026 18:19:40 +0900 Subject: [PATCH 3/4] docs: the checklist's sentence on the library's name Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42 --- README.ko.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.ko.md b/README.ko.md index 30d0e72..3dc020d 100644 --- a/README.ko.md +++ b/README.ko.md @@ -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)): 공유 라이브러리 이름에는 이제 주 버전이 들어 있고(D75), 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: 릴리스 워크플로를 바꿔야 합니다). diff --git a/README.md b/README.md index fb950f1..05577aa 100644 --- a/README.md +++ b/README.md @@ -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 carries the major version now (D75), 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). From 9d7bfb3fef1cafdeaaf3d5db45540fa239ec0f38 Mon Sep 17 00:00:00 2001 From: harry Date: Thu, 19 Nov 2026 18:31:28 +0900 Subject: [PATCH 4/4] fix(ffi): the documented C example build, the C locale, the script's checks A review of the versioned library name found that the README's own recipe for the C example built against cargo's output directory, which has no file under the name the program now records, so the program could not start. The recipe, the CMake file's comment and its default directory now use the packaged directory, as scripts/check_c_example.sh does. readelf's labels are translated, so its SONAME line is read with LC_ALL=C in the script and in the test. scripts/package_ffi.sh now reads the library's own name before it copies anything, so a library built before a change of version fails without leaving a misnamed file behind; it accepts only the exact --with-static, says that relative paths are the repository's, and the README no longer makes a stray `lib` directory at the root. The README's sentence on what a program never loads says Linux and macOS and from this change on, and which file to ship; CONTRIBUTING tells the 1.0.0 release to change the names the README gives. Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42 --- CONTRIBUTING.md | 2 +- crates/emberwave-ffi/README.md | 7 ++-- .../emberwave-ffi/examples/c/CMakeLists.txt | 13 +++++-- crates/emberwave-ffi/tests/exports.rs | 2 + scripts/package_ffi.sh | 39 ++++++++++++------- 5 files changed, 42 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11169b7..579cc24 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. The release workflow packages the C library with `scripts/package_ffi.sh`, which gives the shared library the versioned name it carries (D75). `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 diff --git a/crates/emberwave-ffi/README.md b/crates/emberwave-ffi/README.md index f863231..828a17d 100644 --- a/crates/emberwave-ffi/README.md +++ b/crates/emberwave-ffi/README.md @@ -19,7 +19,7 @@ To build it yourself, with Rust 1.87 or newer: ```sh cargo build --release -p emberwave-ffi # target/release: the shared library, as libemberwave_ffi.so or .dylib -scripts/package_ffi.sh target/release lib # gives it its versioned name, with the unversioned one as a link +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 ``` @@ -30,7 +30,7 @@ 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.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 one major version never loads another. 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. 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 @@ -152,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 diff --git a/crates/emberwave-ffi/examples/c/CMakeLists.txt b/crates/emberwave-ffi/examples/c/CMakeLists.txt index 9878c74..3267b0a 100644 --- a/crates/emberwave-ffi/examples/c/CMakeLists.txt +++ b/crates/emberwave-ffi/examples/c/CMakeLists.txt @@ -3,18 +3,23 @@ # emberwave_encode (encode.c). # # cargo build --release -p emberwave-ffi -# cmake -S crates/emberwave-ffi/examples/c -B target/c-example -DEMBERWAVE_LIB_DIR=target/release +# scripts/package_ffi.sh target/release target/c-example/lib +# cmake -S crates/emberwave-ffi/examples/c -B target/c-example -DEMBERWAVE_LIB_DIR=target/c-example/lib # cmake --build target/c-example --config Release # -# EMBERWAVE_LIB_DIR is the cargo output directory (target/debug or -# target/release), relative to the repository root or absolute. +# EMBERWAVE_LIB_DIR is a directory with the library under the name it gives +# itself, which a program linked against it looks for (decision D75): cargo makes +# libemberwave_ffi.so or .dylib without the major version, and +# `scripts/package_ffi.sh target/release target/c-example/lib` makes the directory +# from it, with the versioned file and the unversioned link. Relative to the +# repository root or absolute. On Windows the cargo output directory does as it is. cmake_minimum_required(VERSION 3.16) project(emberwave_example C) set(EMBERWAVE_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../../..") # A STRING, not a PATH: CMake would resolve a relative PATH against the # current directory before this file sees it. -set(EMBERWAVE_LIB_DIR "target/release" CACHE STRING "Where cargo put the emberwave-ffi library") +set(EMBERWAVE_LIB_DIR "target/c-example/lib" CACHE STRING "A directory with the emberwave-ffi library under its own name") get_filename_component(EMBERWAVE_LIB_DIR_ABSOLUTE "${EMBERWAVE_LIB_DIR}" ABSOLUTE BASE_DIR "${EMBERWAVE_ROOT}") add_library(emberwave SHARED IMPORTED) diff --git a/crates/emberwave-ffi/tests/exports.rs b/crates/emberwave-ffi/tests/exports.rs index af7ffc6..9636be2 100644 --- a/crates/emberwave-ffi/tests/exports.rs +++ b/crates/emberwave-ffi/tests/exports.rs @@ -270,7 +270,9 @@ fn own_name(library: &PathBuf) -> (String, Option<(String, String)>) { )), ) } else { + // readelf's labels are translated; the C locale keeps the ones parsed below. let output = Command::new("readelf") + .env("LC_ALL", "C") .arg("-d") .arg(library) .output() diff --git a/scripts/package_ffi.sh b/scripts/package_ffi.sh index 4ddfd2c..8cf2e19 100755 --- a/scripts/package_ffi.sh +++ b/scripts/package_ffi.sh @@ -17,44 +17,57 @@ # --with-static also copy the static library (`libemberwave_ffi.a`, or # `emberwave_ffi.lib` on Windows), which a release builds apart # -# Needs readelf on Linux and otool on macOS for the check. +# A relative SRC or DEST is relative to the root of the repository, wherever +# the script is run from. The library's own name is checked before anything is +# copied, so a library built before a change of version fails the script +# without leaving a misnamed file behind. Needs readelf on Linux and otool on +# macOS for the check. set -euo pipefail cd "$(dirname "$0")/.." SRC=${1:?usage: scripts/package_ffi.sh SRC DEST [--with-static]} DEST=${2:?usage: scripts/package_ffi.sh SRC DEST [--with-static]} -WITH_STATIC=${3:-} +WITH_STATIC= +case "${3:-}" in + "") ;; + --with-static) WITH_STATIC=1 ;; + *) echo "usage: scripts/package_ffi.sh SRC DEST [--with-static]" >&2; exit 2 ;; +esac +[ $# -le 3 ] || { echo "usage: scripts/package_ffi.sh SRC DEST [--with-static]" >&2; exit 2; } # The workspace's version, which the crates take: its first number is the major. version=$(sed -n '/^\[workspace.package\]/,/^\[/{s/^version = "\([0-9]*\)\..*/\1/p;}' Cargo.toml) major=${version:?no version in Cargo.toml} -mkdir -p "$DEST" case "$(uname -s)" in Linux) versioned=libemberwave_ffi.so.$major - cp "$SRC/libemberwave_ffi.so" "$DEST/$versioned" - ln -sf "$versioned" "$DEST/libemberwave_ffi.so" - [ -z "$WITH_STATIC" ] || cp "$SRC/libemberwave_ffi.a" "$DEST/" - soname=$(readelf -d "$DEST/$versioned" | sed -n 's/.*Library soname: \[\(.*\)\]/\1/p') + # readelf's labels are translated: the C locale keeps them as parsed here. + soname=$(LC_ALL=C readelf -d "$SRC/libemberwave_ffi.so" | sed -n 's/.*Library soname: \[\(.*\)\]/\1/p') [ "$soname" = "$versioned" ] || { - echo "the library's SONAME is '$soname', not $versioned" >&2 + echo "the library's SONAME is '$soname', not $versioned: build it again" >&2 exit 1 } + mkdir -p "$DEST" + cp "$SRC/libemberwave_ffi.so" "$DEST/$versioned" + ln -sf "$versioned" "$DEST/libemberwave_ffi.so" + [ -z "$WITH_STATIC" ] || cp "$SRC/libemberwave_ffi.a" "$DEST/" ;; Darwin) versioned=libemberwave_ffi.$major.dylib - cp "$SRC/libemberwave_ffi.dylib" "$DEST/$versioned" - ln -sf "$versioned" "$DEST/libemberwave_ffi.dylib" - [ -z "$WITH_STATIC" ] || cp "$SRC/libemberwave_ffi.a" "$DEST/" - name=$(otool -D "$DEST/$versioned" | tail -n 1) + name=$(otool -D "$SRC/libemberwave_ffi.dylib" | tail -n 1) [ "$name" = "@rpath/$versioned" ] || { - echo "the library's install name is '$name', not @rpath/$versioned" >&2 + echo "the library's install name is '$name', not @rpath/$versioned: build it again" >&2 exit 1 } + mkdir -p "$DEST" + cp "$SRC/libemberwave_ffi.dylib" "$DEST/$versioned" + ln -sf "$versioned" "$DEST/libemberwave_ffi.dylib" + [ -z "$WITH_STATIC" ] || cp "$SRC/libemberwave_ffi.a" "$DEST/" ;; *) # Windows (Git Bash): the names do not change. + mkdir -p "$DEST" cp "$SRC/emberwave_ffi.dll" "$SRC/emberwave_ffi.dll.lib" "$DEST/" [ -z "$WITH_STATIC" ] || cp "$SRC/emberwave_ffi.lib" "$DEST/" ;;