@cutils/ffi
@cutils/ffi
Shared scriptc FFI spec used by @cutils/sqlite and by later native packages (pty, keyring). Format 7, span ABI, structs packed as bytes/mutable-bytes.
Surface
| API | Notes |
|---|---|
FFI_FORMAT |
7 — the format every manifest here declares |
FfiManifest, FfiFunctionDecl |
the authored JSON shape (snake_case ffi_format) |
FfiParamClass, FfiReturnClass, FfiCallbackParamClass |
scriptc’s three per-position class sets |
writeI32 / writeU32 / writeI64 / readI32 / readU32 / readI64 |
little-endian field accessors |
ensure / copyOut |
scratch helpers for mutable-bytes out params |
encodeEchoPoint / decodeEchoPoint / echoPoint |
the Rust EchoPoint proof, packed and unpacked |
The class sets differ on purpose: string and bytes are never returns, mutable-bytes is outbound-only, and cstring is callback-only. One shared union would let TypeScript accept a manifest scriptc rejects.
ABI classes
| Manifest class | TypeScript | Native C/Rust |
|---|---|---|
i32 / u32 / f64 / … |
number |
matching scalar |
i64 / u64 / pointer |
bigint |
i64 / u64 / void * |
string / bytes |
string / Uint8Array |
(const uint8_t *data, size_t len) — not NUL-terminated |
mutable-bytes |
Uint8Array |
(uint8_t *buf, size_t len), caller-owned |
Buffer-out convention: return >= 0 required bytes; if that exceeds len, write nothing and let the wrapper grow. -1 is a domain null or an input error.
Structs are not a manifest type. EchoPoint is 24 bytes on little-endian hosts: i32 x, i32 y, u32 flags, 4 bytes of padding, i64 value.
Compile to ELF
cp node_modules/@cutils/ffi/elf/shims.d.ts ./shims.d.ts
scriptc build app.ts --npm-static @cutils/ffi \
--ffi node_modules/@cutils/ffi/ffi.json
ffi.json points at the shipped ./build/libcutils_ffi_echo.a. Do not pass vendor/manifest.json from a consumer — its libraries path is repo-layout.
See the package README for the full ELF compile recipe and the echo smoke.