uniffi-cdylib-filename-docs-rename-step
I diagnosed the issue and wrote a verified, self-contained solution to ~/SOLUTION.md.
Root cause: Two distinct names were conflated:
- Actual build artifact: libhilo_ffi.so (from Cargo library target hilo_ffi).
- Loader-expected file: libuniffi_hilo.so (from UniFFI's cdylib_name, which defaults to uniffi_{namespace} = uniffi_hilo).
The docs presented the loader's expected filename as if it were the build output and never documented the rename between them.
Verification done against the real pinned binder (not guessed):
- Downloaded/extracted uniffi_bindgen==0.28.3.
- Generated bindings from a namespace hilo UDL → confirmed the literal libname = libname.format("uniffi_hilo") (Linux path lib{}.so).
- Confirmed source: uniffi_bindgen/src/bindings/python/mod.rs defaults cdylib_name to format!("uniffi_{}", namespace).
- End-to-end: import hilo failed with OSError: .../libuniffi_hilo.so: cannot open shared object file when only libhilo_ffi.so was present; succeeded after cp libhilo_ffi.so libuniffi_hilo.so.
- Also verified the durable alternative: uniffi.toml [bindings.python] cdylib_name = "hilo_ffi" regenerates the loader to look for libhilo_ffi.so directly (no copy needed).
The fix (both options documented):
1. Docs + explicit rename (requested pattern): name the real artifact, then cp/rename per platform to the loader-expected name (libuniffi_hilo.so / .dylib / uniffi_hilo.dll), with a Makefile to prevent drift.
2. Root fix (recommended): pin cdylib_name = "hilo_ffi" in uniffi.toml and regenerate.
The document includes a symptom section, root-cause analysis with the exact template/source literals, copy-paste commands, an end-to-end verification section with real observed output, and a checklist.
# Evidence - Problem class: uniffi-cdylib-filename-docs-rename-step - Model: openrouter/deepseek/deepseek-v4.1-flash - Solved: 2026-09-24T13:39:47.642Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "UniFFI kotlin multiplatform setup builds libhilo_ffi.so but Python consumers/docs referenced libuniffi_hilo.so which is never produced at that path. Fix pattern: name the actual cdylib artifact in docs AND document the explicit cp/rename step to the loader-expected name; verify the expected name against uniffi-bindgen (0.28.3) template literals rather than guessing.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "uniffi-cdylib-filename-docs-rename-step", "provider": "openrouter", "solved_at": "2026-09-24T13:39:47.642Z", "version": ""}I diagnosed the issue and wrote a verified, self-contained solution to ~/SOLUTION.md.
Root cause: Two distinct names were conflated:
- Actual build artifact: libhilo_ffi.so (from Cargo library target hilo_ffi).
- Loader-expected file: libuniffi_hilo.so (from UniFFI's cdylib_name, which defaults to uniffi_{namespace} = uniffi_hilo).
The docs presented the loader's expected filename as if it were the build output and never documented the rename between them.
Verification done against the real pinned binder (not guessed):
- Downloaded/extracted uniffi_bindgen==0.28.3.
- Generated bindings from a namespace hilo UDL → confirmed the literal libname = libname.format("uniffi_hilo") (Linux path lib{}.so).
- Confirmed source: uniffi_bindgen/src/bindings/python/mod.rs defaults cdylib_name to format!("uniffi_{}", namespace).
- End-to-end: import hilo failed with OSError: .../libuniffi_hilo.so: cannot open shared object file when only libhilo_ffi.so was present; succeeded after cp libhilo_ffi.so libuniffi_hilo.so.
- Also verified the durable alternative: uniffi.toml [bindings.python] cdylib_name = "hilo_ffi" regenerates the loader to look for libhilo_ffi.so directly (no copy needed).
The fix (both options documented):
1. Docs + explicit rename (requested pattern): name the real artifact, then cp/rename per platform to the loader-expected name (libuniffi_hilo.so / .dylib / uniffi_hilo.dll), with a Makefile to prevent drift.
2. Root fix (recommended): pin cdylib_name = "hilo_ffi" in uniffi.toml and regenerate.
The document includes a symptom section, root-cause analysis with the exact template/source literals, copy-paste commands, an end-to-end verification section with real observed output, and a checklist.
# Evidence - Problem class: uniffi-cdylib-filename-docs-rename-step - Model: openrouter/deepseek/deepseek-v4.1-flash - Solved: 2026-09-24T13:39:47.642Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "UniFFI kotlin multiplatform setup builds libhilo_ffi.so but Python consumers/docs referenced libuniffi_hilo.so which is never produced at that path. Fix pattern: name the actual cdylib artifact in docs AND document the explicit cp/rename step to the loader-expected name; verify the expected name against uniffi-bindgen (0.28.3) template literals rather than guessing.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "uniffi-cdylib-filename-docs-rename-step", "provider": "openrouter", "solved_at": "2026-09-24T13:39:47.642Z", "version": ""}