diff --git a/docs/handoffs/HANDOFF-cimport-ptr.md b/docs/handoffs/HANDOFF-cimport-ptr.md new file mode 100644 index 0000000..e082247 --- /dev/null +++ b/docs/handoffs/HANDOFF-cimport-ptr.md @@ -0,0 +1,47 @@ +# Handoff — the pointer arm `agrees` already promised + +`lib/cimport.ml`'s `agrees` decides whether a hand-written `declare-c` and the C header +say the same thing. Its comment has always listed three differences that are "expected and +are not reported"; the code implements two of them. The missing one — *a `(Ptr T)` where +the header says `T *`* — is what `../PORTING.md` §A.1 and §A.2 ran into, and it is why +`GetCodepointPrevious` cannot be bound honestly and why `UpdateTexture` has to be handed +`(addr (.r (at (slice-from-ptr pixels n) 0)))`. + +This file is the running record of building that arm. + +## The plan + +1. A `ptr_agrees` beside `agrees`, consulted only at the two `declare-c` sites in + `diff_bound`, where the C spelling is still in hand. `agrees` itself is left alone: + `check_structs` uses it for field *widths*, and loosening it there is the hazard the + check exists to catch. +2. Breadth, decided rather than fallen into — see "What it accepts" below. +3. Rewrite the comment at `lib/cimport.ml:1291` so it describes the code instead of + promising it, and take the rotting binding count out of it. +4. Use it: `get-codepoint-previous-raw` in `vendor/raylib/raylib.flan`, and the + `(Ptr Color)` binding for `UpdateTexture`. Delete both workarounds. +5. `docs/PORTING.md` §A.1 and §A.2 annotated closed in the file's existing style. + +## What it accepts (to be confirmed as it is built) + +- `(Ptr T)` against a C `T *` for the same `T`. +- `(Ptr u8)` against `char *` — a byte is a byte, and the two spellings of one are not a + width disagreement. Scoped to the pointee, never to `agrees` at large. +- `(Ptr T)` for any `T` against `void *`. `value_ty` already *invents* `(Ptr u8)` for a + `void *`, so the check as it stands enforces cimport's own guess as if the header had + said it. +- `const` does not enter into it, because a non-const `char *` parameter makes `param_ty` + refuse and `diff_bound` skips a parameter it cannot render at all. + +## What it still refuses + +- `(Ptr A)` against `B *` for different named `A` and `B`. +- Anything that is not a pointer on the Flan side against a C pointer, and the reverse. + +## Status + +- [ ] the arm +- [ ] the comment +- [ ] tests, positive and negative +- [ ] the two raylib bindings +- [ ] PORTING.md