Joseph Ferano
d6fc15474b
The author: "I think I prefer length over len, because then I'll use len as the variable name". One arm in check.ml, one row in the table beside it, and every (len x) in lib, test, examples, vendor, spike, docs, web, emacs, plan.org and NEXT.md rewritten. Shadowing and builtin/ had already taken most of the sting out: a (defn len ...) was legal and won in its own file, and builtin/len reached past it. What was left is that len was still a builtin — the defn earned a warning, and a wrapper had to say builtin/ at every inner call. Now there is nothing under the short name: len is an ordinary identifier in every position, which is what (let [len (length xs)] ...) wants. length takes over as shadowing's worked example rather than the feature losing one. shadow-builtin.flan, builtin-qualified.flan, pkgs/shadowed and the builtin/ rows in test_flan move to it and go on testing shadowing. A call to a len nothing defines is answered where an unknown function is, after every table and after the shadowing guard, so a program with its own len never reaches it. The sentence is said rather than guessed at — len and length are three edits apart and the did-you-mean's net is one — and the call is written back out through spell_arg, as-slice's spelling lifted out of it and now shared, so what is printed compiles. sand.flan:33 still calls the old name and is the author's to change; until it does, test_acceptance and test_session abort there. Both were run green against a copy with that one line changed. FIX.org says so.
90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# Handoff — the last two raylib ports
|
|
|
|
Two examples, `text_codepoints_loading` and `textures_image_processing`, ported into
|
|
`examples/`. This file is the running record: what is done, what was decided without being
|
|
able to ask, and what is still open. `../PORTING.md` has the findings that outlive the port —
|
|
its last section, "Porting the raylib examples — the last two" — and this file has the
|
|
state of the work.
|
|
|
|
## Status — done
|
|
|
|
- [x] `examples/text-codepoints-loading.flan` — builds
|
|
- [x] `examples/textures-image-processing.flan` — builds
|
|
- [x] `test/programs/raylib-codepoints.flan` and `test/programs/raylib-image-processing.flan`,
|
|
both in the acceptance table, both gated on libraylib, both run plain and at `-O0`
|
|
- [x] `../PORTING.md` section for this round
|
|
- [x] `dune test --root .` green
|
|
|
|
Four commits, each one a working state:
|
|
|
|
1. the plan and the open question (this file's first version)
|
|
2. `PixelFormat`, the one binding this round added
|
|
3. the image-processing example and its headless case
|
|
4. the codepoints example and its headless case
|
|
|
|
## Open questions for the author
|
|
|
|
1. **Vendor `DotGothic16-Regular.ttf`?** `text_codepoints_loading` draws Japanese, and
|
|
there is no CJK font in this tree. The font is SIL OFL 1.1 and therefore
|
|
redistributable, but it is 2 MB of binary in a repository whose only binary asset is a
|
|
1 KB PNG, and that is a call about the repository rather than about the port. The
|
|
example works either way: it looks for
|
|
`examples/resources/DotGothic16-Regular.ttf`, and if it is not there raylib hands back
|
|
the default font, the kana draw as boxes, and the program says on screen why. Drop the
|
|
TTF in and the glyphs appear with nothing else to change. `~/Repositories/raylib/examples/text/resources/`
|
|
has the file and its OFL notice.
|
|
|
|
2. **`lib/cimport.ml`'s `agrees` promises an arm it does not have.** The comment at
|
|
`lib/cimport.ml:1291` lists, among the differences that are "expected and are not
|
|
reported", *"a `(Ptr T)` where the header says `T *` and the hand-written line chose
|
|
something more specific"*. The function implements the enum-against-i32 arm and nothing
|
|
else. That missing arm is the only thing standing between this round's two refused
|
|
bindings and ordinary binding work — see `../PORTING.md` §A.1 and §A.2, which have the
|
|
exact declarations and the exact error. **Not built: it is a compiler change and the
|
|
freeze is on.** It is small and it is well specified, and it is the thing to do first if
|
|
these two ports are ever revisited.
|
|
|
|
3. The image-processing port keeps the C's `LoadImageColors` → `UpdateTexture` round trip
|
|
even though `(.data im-copy)` is the same bytes and already the right type. Kept
|
|
because it is what the C does and because nothing else in the corpus exercises that
|
|
pair. If you would rather the example were the short version, the comment on
|
|
`reload-texture` says exactly what to delete.
|
|
|
|
## Deviations from the upstream C, all deliberate, all commented in place
|
|
|
|
- **Neither asset is vendored.** `parrots.png` has no licence at all in raylib's own
|
|
LICENSE.md, so the image-processing example generates its picture. The generated image is
|
|
asymmetric in both axes and has hard edges on purpose — a symmetric one makes the two
|
|
flips indistinguishable and the blur invisible.
|
|
- **The duplicate removal is a build-up, not a compaction.** The C's shift-the-tail-down
|
|
loop reads one element past the end of its allocation, which C tolerates and Flan's
|
|
bounds check does not.
|
|
- **The codepoint cursor clamps at both ends.** The C's runs off both.
|
|
- **`GetCodepointPrevious` is not called**, because it cannot be: a Flan string reaches C
|
|
as a NUL-terminated copy and that function reads backwards out of the pointer. Four
|
|
lines of continuation-byte walking replace it, and the headless case pins them against
|
|
`LoadCodepoints`.
|
|
- **The UP key in image processing wraps to 7 and not to 8**, which is the C's own
|
|
off-by-one, left as it is so that the port and the example it claims to be do not
|
|
disagree.
|
|
|
|
## Things a next lane should know
|
|
|
|
- `examples/` is **not** compiled by `dune test`. `test/dune` globs it so that imports
|
|
resolve, nothing more. `flan build <example>` is the only proof an example compiles, and
|
|
it is worth running on all of them after any change to `vendor/raylib`.
|
|
- The header check in `vendor/raylib/headers` runs on **every ordinary build**, not only on
|
|
`flan generate-c`. A hand-written `declare-c` that disagrees with `raylib-5.5.h` therefore
|
|
breaks every build in the tree, not just regeneration. That is what makes open question 2
|
|
a blocker rather than an inconvenience.
|
|
- `(string (slice b off (length b)))` is the idiom for a C `char *` cursor into the middle of a
|
|
string, and it costs nothing. It is correct for every entry point that reads forwards and
|
|
wrong for every one that reads backwards.
|
|
- `slice-from-ptr` is how a raylib pointer-plus-count becomes something with a length. Both
|
|
new test programs lean on it.
|
|
|
|
## Log
|
|
|
|
- Started from `957ba07` on `dev-loop`. The worktree came up on a much older commit
|
|
(`2c232dd`, no `examples/` directory at all) and was reset onto the branch tip first.
|