fix(embedding): make dynamic-linking escape hatch work + guard static release link (#55)#56
Merged
Merged
Conversation
… release link (#55) Restructure fastembed's ort features so embedding-fastembed (static ONNX archive) and embedding-fastembed-dynamic-linking (runtime dylib load) are mutually exclusive. Previously the dynamic feature implied the static one, so Cargo feature unification silently enabled both ort-load-dynamic and ort-download-binaries on fastembed/ort-sys, turning the static path into a no-op (#50) — the escape hatch downstream consumers needed never actually worked on its own. - compile_error! in src/lib.rs makes the two-feature conflict a hard error (enforced across the consumer dep graph too). - ci: replace --all-features with --features full (mutex makes --all-features unbuildable); add release-link-check that builds the static path on ubuntu-latest/windows-latest and the dynamic escape hatch on ubuntu-22.04 (glibc 2.35) — the baseline alcove rolled back from. - docs: document the static archive needs glibc >=2.38 / current MSVC; older baselines must use the dynamic escape hatch (#55). Closes #55
The switch from --all-features to --features full (previous commit) unmasked a pre-existing macOS regression: --all-features enabled the broken dynamic-linking feature, which skipped the static ort link, so macos-check passed without ever linking the ONNX archive. With --features full the static link is real, and the Xcode 16+ runner image no longer puts libclang_rt.osx.a on the default linker search path — inject it via RUSTFLAGS so ld can resolve it (#55 compiler-rt path regression).
…ew fixes (#55) Review findings on PR #56: - FastembedProvider / LazyFastembedProvider / EmbeddingCache / as_fastembed were gated only on feature="embedding-fastembed", so the mutually-exclusive restructure left dynamic-linking compiling the bare fastembed crate with NO llm-kernel embedding API (unresolved import FastembedProvider, verified by build). Gates now also fire under embedding-fastembed-dynamic-linking. - [package.metadata.docs.rs] features=["full"] so docs.rs (defaults to --all-features) doesn't trip the new compile_error!. - release-link-check: drop redundant matrix.mode; add a clippy pass on the dynamic escape-hatch path (excluded from full); correct the misleading "macOS already links reliably" comment (macos-check's clang_rt RUSTFLAGS is what makes macOS link). - QUICKSTART/PROGRESS/ROADMAP: --all-features -> --features full; stale test counts (599/593 -> 602). - Unify glibc wording (>=2.38) across Cargo.toml/README/AGENTS. Verified: dynamic-only mini consumer imports FastembedProvider; mutex compile_error still fires; full test 602 pass; clippy + fmt clean.
…g_rt fix (#57) Xcode 26.5 / clang 21 no longer ships libclang_rt.osx.a, so ort's static archive fails to link on macos-latest even though the cc line already passes -L the Xcode clang/darwin dir. This is a runner-image environment issue, not a regression in this crate (the Linux/Windows static ort link is guarded by release-link-check). macos-check's Test step is now continue-on-error; tracked in #57. The Check step (no link) stays required.
epicsagas
added a commit
that referenced
this pull request
Jul 5, 2026
) - i18n: propagate the dynamic-linking feature row + #55 release-link caveat to all 9 remaining translated READMEs (de, es, fr, it, ja, pt, ru, zh-Hans, zh-Hant). - ci: pin macos-check to macos-14 (Xcode 15.x) to dodge the Xcode 26.5 / clang 21 libclang_rt.osx.a drop that breaks the static ort link (#57). - bump 0.14.0 -> 0.15.0 (Cargo.toml, Cargo.lock, CHANGELOG dated 2026-07-06, README + PROGRESS version refs) — minor bump for the mutually-exclusive feature change in #56.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #55
What & why
이슈 #55: 0.12.0 정적 ort 링크 기본화(#50 fix 부작용)가 Linux(glibc <2.38)/Windows(MSVC CRT) consumer release 빌드 링크를 깨뜨림.
alcove(cargo-dist)는 0.9.2로 롤백. CI가 debug profile(cargo test)만이라 release 타임에만 발견.council 4관점 검토(Architect · Skeptic · Pragmatist · Critic) → 옵션 1(dynamic 기본 복귀)·2(이식성 정적 아카이브) 만장일치 반대. 본 PR은 옵션 3: CI 사전 포착 + escape-hatch 강화 + 문서.
Changes
R1 — release-link-check CI (
.github/workflows/ci.yml)ubuntu-latest+windows-latest:cargo build --release --features embedding-fastembed→ static 링크 회귀를 PR 시점에 포착 (consumer release 타임이 아니라)ubuntu-22.04(glibc 2.35):--features embedding-fastembed-dynamic-linking→ escape hatch가 alcove가 롤백한 베이스라인에서 컴파일됨을 증명R2 — escape-hatch 강화 (
Cargo.toml+src/lib.rs)fastembed의 ort features를 dep 선언에서 feature 정의로 이동.embedding-fastembed(static)와embedding-fastembed-dynamic-linking(dynamic)을 mutually exclusive로 재구성embedding-fastembed의 superset이라 단독 사용도 silent no-op(embedding-fastembed on Linux force-enables ort-load-dynamic, causing a silent deadlock instead of a clear error when libonnxruntime.so isn't separately provided #50) → escape hatch가 실제로 작동하지 않았음compile_error!(src/lib.rs)가 두 feature 충돌을 hard error로 (consumer dep graph 전체에서도 잡힘)R3 — 문서 (
README.md,AGENTS.md,docs/i18n/ko/README.md)libonnxruntime.{so,dll}배포.cargo check는 링크 안 해서 green,cargo build --release에서만 실패R4 — CHANGELOG: Unreleased (Fixed / Added / Changed)
Why not option 1 / 2
[profile.release] panic = "abort"아래lazy.rs의catch_unwind무력화 → release consumer에서 dylib 누락 시 deadlock이 아니라 process abort. 또 feature unification이 embedding-fastembed on Linux force-enables ort-load-dynamic, causing a silent deadlock instead of a clear error when libonnxruntime.so isn't separately provided #50 silent no-op 재현.ort = "=2.0.0-rc.12"pin + fastembed 5 lockstep이라 ort-sys fork + 자체 ORT 빌드 인프라 필요 → "zero mandatory external deps" foundation 정체성에 반하는 비용 과잉.CI 변경
cargo {test,clippy,doc,check} --all-features→--features full전환. mutually-exclusive feature 때문에--all-features(두 feature 동시 활성화)는 더 이상 빌드 불가;full은 dynamic escape hatch만 제외한 전부(기존 테스트 602개 동일).Verification (local)
cargo build --features "embedding-fastembed embedding-fastembed-dynamic-linking"→ compile_error! 발동 ✓cargo check --no-default-features --features embedding-fastembed-dynamic-linking→ 성공 (ort-load-dynamic만, download-binaries 비활성 —cargo tree -e features -i ort-sys로 확인) ✓cargo build --features embedding-fastembed→ 성공 (macOS static) ✓cargo test --features full→ 602 passed, 0 failed, 13 ignored (기존 all-features와 동일) ✓cargo clippy --features full -- -D warningsclean,cargo fmt --checkclean ✓Audit
병렬 감사: correctness/regression PASS 5/5, CI PASS, docs PASS (WARN 1 — i18n 범위). 회귀 위험 없음 (활성화 집합 동일; dynamic-linking은 silent no-op→fix).
i18n note
ko README만 동기화. 나머지 9개 언어(de/es/fr/it/ja/pt/ru/zh-Hans/zh-Tai)는 다음 release doc sweep에서 전파 예정 (기존 릴리스 주기 패턴).