Skip to content

test(ffi): the shared library exports the header's functions and nothing else - #164

Merged
with-developer merged 2 commits into
mainfrom
feat/ffi-export-list
Nov 16, 2026
Merged

with-developer merged 2 commits into
mainfrom
feat/ffi-export-list

Conversation

@with-developer

Copy link
Copy Markdown
Owner

What changes for a client of the shared library

Nothing: no function, name or behaviour changes, and the library is built as before. This adds a test and a decision record. To revert, drop crates/emberwave-ffi/tests/exports.rs.

Purpose

Before 1.0 the C library's export table is part of what a client can depend on, and nothing checked it.

What was measured (release 0.18.1, wgpu 30.0.2)

  • Linux shared library (nm -D --defined-only, Debian 12 container, current stable Rust): the 62 functions of include/emberwave.h and nothing else.
  • macOS shared library (nm -gU): the same 62, and 4 more: ___CLASS_, ___DROP_FLAG_OFFSET_, ___IVAR_OFFSET_ and ___REGISTER_CLASS_ followed by RawWindowMetalLayer, the Objective-C class registration of a class that raw-window-metal declares with objc2. No client uses them.
  • Static library: about 18,600 external symbols, nearly all Rust-mangled. A static library has no export table to restrict.

Changes

  • crates/emberwave-ffi/tests/exports.rs (macOS and Linux; the file is empty on Windows, which has no nm): builds the shared library through cargo build, finds it in cargo's own report, reads its table with nm and fails unless it is exactly the functions of the header. The header is the list, so a new C function cannot be forgotten and a stray name cannot pass. One documented exception on macOS: the Objective-C class names above.
  • ARCHITECTURE.md D73 with the measurement, and what was not done: hiding the four macOS names. ld64 refuses -unexported_symbols_list together with an exported list and rustc passes its own, so a linker flag cannot remove them; there is no standard tool to remove them after linking. A version script or .def file for Linux and Windows would fight rustc's own, which already gives exactly the functions.
  • A line in the FFI crate's README.

Testing

  • cargo test -p emberwave-ffi passes on macOS; the new test passes on macOS and in a Linux container.
  • The test fails as it should: with a #[unsafe(no_mangle)] pub extern "C" fn stray_symbol_for_the_test() added to src/lib.rs it reports that name as exported but not declared (checked, then removed).
  • fmt and clippy with -D warnings pass.

…ing else

Before 1.0 the C library's export table is part of what a client can depend
on, and nothing checked it. Measured: the Linux library exports the 62
functions of emberwave.h and nothing else; the macOS one also exports four
Objective-C class registration names of raw-window-metal's
RawWindowMetalLayer, which no client uses and which cannot be hidden by a
linker flag (ld64 refuses an unexported list beside an exported one, and
rustc passes its own). The static library has no export table to restrict.

tests/exports.rs builds the shared library, reads its table with nm on macOS
and Linux, and fails unless it is exactly the functions of the header, with
the four Objective-C names per class as the one documented exception on
macOS. The header is the list, so a new C function cannot be forgotten and a
stray name cannot pass. Decision D73 records the measurement and what was
not done. No client-visible change.

Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42
…n exactly

A review of the export test found that its nested cargo build ignored
`--target-dir`, a relative `CARGO_TARGET_DIR`, `--target` and custom
profiles, and failed on a read-only source tree. The test now reads the
target directory, the triple and the profile from its own path and passes
them on, and the macOS exception is exactly the four names of
RawWindowMetalLayer, so a class of another dependency fails it until
someone has looked. The doc comment, the decision's reference (D69, not
D70), the README's claim about Windows, which the test does not cover, and
CONTRIBUTING's list of tests are corrected.

Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42
@with-developer
with-developer merged commit b3450c1 into main Nov 16, 2026
7 checks passed
@with-developer
with-developer deleted the feat/ffi-export-list branch November 16, 2026 13:57
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.

1 participant