diff --git a/README.md b/README.md index 89b1923..dc456a3 100644 --- a/README.md +++ b/README.md @@ -136,15 +136,18 @@ you need a name that differs from the proc. ### ABI format -The default wire format is `cbor`. Override the library default with -`declareLibrary("lib", Lib, defaultABIFormat = "c")`, or per annotation with an -`"abi = ..."` spec, e.g. `{.ffi: "abi = c".}`. +The wire format is chosen **in code**, never by a compile flag. Override the +library default with `declareLibrary("lib", Lib, defaultABIFormat = "c")`, or +per annotation with an `"abi = ..."` spec, e.g. `{.ffi: "abi = c".}`. The +`-d:targetLang` flag (below) picks which *language* the bindings are emitted +for; it does not change the wire. -`cbor` is the fully-supported format: every proc, ctor, dtor and event -serializes through the generic CBOR path, and all four binding backends emit +`cbor` is the default and fully-supported format: every proc, ctor, dtor and +event serializes through the generic CBOR path, and all binding generators emit working callers for it. -`abi = c` (flat C-struct wire, generated by `-d:targetLang=c_abi`) is newer and +`abi = c` is a newer, flat C-struct wire (no CBOR round-trip). Callers for it +are emitted only by the dedicated `c_abi` generator (`-d:targetLang=c_abi`). It carries two honest limits today: - **Events are CBOR-only.** Applying `abi = c` to an `{.ffiEvent.}` proc is a @@ -153,10 +156,10 @@ carries two honest limits today: - **All-scalar `abi = c` procs are dropped from the foreign bindings.** A `{.ffi: "abi = c".}` method whose every param and return is a plain scalar takes the CBOR-free scalar fast path at runtime, but the foreign codegen for - that inline-args shape is a follow-up — such procs are omitted from the - generated `.h`. Give a proc at least one non-scalar (struct / `seq` / - `Option`) param or return, or use `abi = cbor`, if you need it in the - bindings. + that inline-args shape is a follow-up (tracked in #120) — such procs are + omitted from the generated `.h`. Give a proc at least one non-scalar + (struct / `seq` / `Option`) param or return, or use `abi = cbor`, if you need + it in the bindings. ## Placement of `genBindings()` @@ -184,7 +187,9 @@ nim c --app:lib --noMain --nimMainPrefix:libmylib mylib.nim **2. Emit the foreign bindings** — same flags, plus the binding defines. This compile runs the generators as a compile-time side effect and produces no -runnable output, so send the binary to `/dev/null`: +runnable output, so send the binary to `/dev/null`. The generated files (for +`targetLang=c`/`c_abi`: the `.h` header your host includes, plus a +`CMakeLists.txt`) land in `-d:ffiOutputDir`: ```sh nim c --app:lib --noMain --nimMainPrefix:libmylib \ @@ -193,7 +198,11 @@ nim c --app:lib --noMain --nimMainPrefix:libmylib \ -o:/dev/null mylib.nim ``` -- `-d:targetLang` — `rust` (default), `cpp`, `c`, `c_abi`, or `cddl`. +- `-d:targetLang` — which generator runs. Two kinds: + - **Language bindings over the CBOR wire:** `rust` (default), `cpp`, `c`. + - **Non-peer generators:** `c_abi` — C bindings that speak the flat `abi = c` + wire instead of CBOR; `cddl` — a CDDL schema of the CBOR wire, not a + language binding at all. - `-d:ffiOutputDir` — where the generated files land. - `-d:ffiSrcPath` — the Nim source path embedded in the generated build files.