|
|
@@ -5,9 +5,9 @@ questions do not have to be re-derived later. It covers `TBITSIZE`,
|
|
|
address arithmetic, set ordering, complex types, pragmas, UTF-8 string
|
|
|
libraries, collections, the TopSpeed B-tree Toolkit, communications,
|
|
|
pyserial, ModBase, network-library design, terminal escape libraries,
|
|
|
-C FFI and GTK4/SQLite/SDL bindings, PIM versus ISO coroutines, external
|
|
|
-assembly, and the dynamic-set design. It is not a commitment to
|
|
|
-implement everything.
|
|
|
+C FFI and GTK4/SQLite/SDL bindings, an audit of the existing gm2
|
|
|
+bindings, PIM versus ISO coroutines, external assembly, and the
|
|
|
+dynamic-set design. It is not a commitment to implement everything.
|
|
|
|
|
|
**State at the time of writing:** suite 310/310, one-shot fixpoint OK
|
|
|
(3,845,439 bytes), per-object fixpoint OK (11 objects), corpus
|
|
|
@@ -2129,7 +2129,253 @@ bindings/gtk4/ GLib/GObject/GTK4 bindings
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 15. Suggested order of future work
|
|
|
+## 15. Audit of existing gm2 bindings: SQLite, SDL, GTK4
|
|
|
+
|
|
|
+The existing GNU Modula-2 binding projects are a strong foundation, but
|
|
|
+they are gm2-targeted and are not drop-in for V3.
|
|
|
+
|
|
|
+### 15.1 `m2SQLITE`
|
|
|
+
|
|
|
+Contents:
|
|
|
+
|
|
|
+- `src/SQLite.def` — thin `FOR "C"` binding of the core SQLite API
|
|
|
+- `lib/SQLiteUtils` — pure-M2 helpers
|
|
|
+- 7 tests
|
|
|
+- examples: `version`, `hello_db`
|
|
|
+- `showcase_all`
|
|
|
+- open/close, exec, prepare/step/finalize, bind/column access,
|
|
|
+ callbacks, BLOB I/O, backup, extended result codes and error strings
|
|
|
+
|
|
|
+Quality:
|
|
|
+
|
|
|
+- good API coverage;
|
|
|
+- sensible opaque handles (`ADDRESS`);
|
|
|
+- `sqlite3_int64` as `LONGINT`;
|
|
|
+- `double` as `REAL`;
|
|
|
+- top-level callback procedure types;
|
|
|
+- in-memory SQLite makes testing easy.
|
|
|
+
|
|
|
+Main V3 blocker: the C string boundary.
|
|
|
+
|
|
|
+The binding declares:
|
|
|
+
|
|
|
+```modula2
|
|
|
+PROCEDURE sqlite3_open (filename: ARRAY OF CHAR;
|
|
|
+ VAR db: DbHandle) : INTEGER;
|
|
|
+```
|
|
|
+
|
|
|
+gm2's `FOR "C"` passes `ARRAY OF CHAR` as `char *`. V3 currently passes
|
|
|
+the **descriptor address** in a normal external call. A generated V3
|
|
|
+call was checked:
|
|
|
+
|
|
|
+```text
|
|
|
+call $check_str(l $CStr_str0)
|
|
|
+```
|
|
|
+
|
|
|
+`$CStr_str0` is `{ length, bytes... }`, not the first character. A C
|
|
|
+function expecting `char *` sees the length word instead.
|
|
|
+
|
|
|
+This must be fixed before SQLite, SDL or GTK can bind to C string
|
|
|
+parameters.
|
|
|
+
|
|
|
+SQLite is otherwise the best first binding.
|
|
|
+
|
|
|
+### 15.2 `m2SDL/SDL3`
|
|
|
+
|
|
|
+There are two independent bindings:
|
|
|
+
|
|
|
+- `m2SDL/SDL2` — older subset
|
|
|
+- `m2SDL/SDL3` — current, more complete
|
|
|
+
|
|
|
+Use SDL3 for new work; keep SDL2 only for legacy compatibility.
|
|
|
+
|
|
|
+SDL3 contents:
|
|
|
+
|
|
|
+- 12 `.def` modules
|
|
|
+- `SDL3Utils`
|
|
|
+- 7 tests
|
|
|
+- 4 examples
|
|
|
+- 7 showcases
|
|
|
+- pure-M2 `SDL3Rect` and `SDL3Key`
|
|
|
+- opaque window/renderer handles as `ADDRESS`
|
|
|
+- event handling through a 128-byte buffer with decoded offsets
|
|
|
+- video, renderer, events, clipboard, filesystem, power, locale
|
|
|
+
|
|
|
+Good design points:
|
|
|
+
|
|
|
+- avoids modelling `SDL_Event` as a V3 variant record;
|
|
|
+- decodes known event fields from a raw buffer;
|
|
|
+- uses `SDLXxx` type aliases;
|
|
|
+- has dummy-driver tests (`SDL_VIDEODRIVER=dummy`,
|
|
|
+ `SDL_AUDIODRIVER=dummy`).
|
|
|
+
|
|
|
+V3 blockers:
|
|
|
+
|
|
|
+1. `SHORTREAL` is 4 bytes in gm2 but currently aliases 8-byte `REAL`
|
|
|
+ in V3. This breaks `SDL_FRect`, `SDL_FPoint`, float draw
|
|
|
+ coordinates and `SetRenderDrawColorFloat`.
|
|
|
+2. C `bool` is 1 byte. V3 `BOOLEAN` is 4 bytes, so `[ BOOLEAN ]`
|
|
|
+ results and bool parameters need a `CBool`/`BYTE` mapping or C
|
|
|
+ wrappers.
|
|
|
+3. The `ARRAY OF CHAR` descriptor/string ABI issue above.
|
|
|
+4. The event decoder uses fixed offsets 0, 28 and 36 and little-endian
|
|
|
+ `LE32`; correct on tested Linux/amd64 but fragile. A C helper using
|
|
|
+ `offsetof` or a C event decoder is safer.
|
|
|
+5. Integer `SDL_Point`/`SDL_Rect` records match C layout; float records
|
|
|
+ do not until true float32 exists.
|
|
|
+
|
|
|
+### 15.3 `m2-GTK4`
|
|
|
+
|
|
|
+This is the largest and most complete binding project.
|
|
|
+
|
|
|
+Contents:
|
|
|
+
|
|
|
+- 432 `.def` modules in `src/`
|
|
|
+- `GtkUtils` and `GtkClosures` helpers in `lib/`
|
|
|
+- C shim `lib/m2gtkshim.c`
|
|
|
+- 45 tests
|
|
|
+- 30 examples
|
|
|
+- 19 demo modules plus the `m2 gtk-demo` browser
|
|
|
+- `tools/gir2def.py` generator
|
|
|
+- `tools/gir_verify.py` verifier
|
|
|
+
|
|
|
+Generator status:
|
|
|
+
|
|
|
+- 301 type modules and 3,719 procedures for Gtk-4.0;
|
|
|
+- 10,256 identifiers verified against installed libraries;
|
|
|
+- generated files are intentionally review/cherry-pick material, not a
|
|
|
+ replacement for the hand-written `src/` modules.
|
|
|
+
|
|
|
+The architecture is good:
|
|
|
+
|
|
|
+- one `FOR "C"` module per GTK/GDK/Gsk/Gio/Adw class;
|
|
|
+- opaque objects as `ADDRESS`;
|
|
|
+- `GtkClosures` provides per-connection callback contexts and destroy
|
|
|
+ handlers;
|
|
|
+- `m2gtkshim.c` provides C-side GObject subclasses for custom widgets,
|
|
|
+ paintables, list models and layout managers.
|
|
|
+
|
|
|
+`GtkClosures` + `m2gtkshim.c` is exactly the kind of trampoline/shim
|
|
|
+layer V3 will need.
|
|
|
+
|
|
|
+V3 blockers:
|
|
|
+
|
|
|
+1. Ignorable-result syntax. GTK modules use:
|
|
|
+
|
|
|
+ ```modula2
|
|
|
+ PROCEDURE gtk_widget_get_visible (...) : [ INTEGER ];
|
|
|
+ ```
|
|
|
+
|
|
|
+ V3 currently rejects `: [ T ]` (`invalid ProcHeading`). Either add
|
|
|
+ this extension or strip it while porting.
|
|
|
+
|
|
|
+2. Varargs. GTK uses declarations such as:
|
|
|
+
|
|
|
+ ```modula2
|
|
|
+ PROCEDURE g_object_new (...; ...) : ADDRESS;
|
|
|
+ PROCEDURE g_object_set (...; ...);
|
|
|
+ PROCEDURE gtk_alert_dialog_new (format: ARRAY OF CHAR; ...) : ...;
|
|
|
+ ```
|
|
|
+
|
|
|
+ V3 has no general `...` declarations/calls. Use typed C wrappers or
|
|
|
+ avoid those APIs in the first subset.
|
|
|
+
|
|
|
+3. C string boundary, as for SQLite/SDL.
|
|
|
+
|
|
|
+4. True 4-byte `float` is needed for `GdkRGBA`, Graphene, Gsk path
|
|
|
+ APIs, GtkFrame alignment and many Adw widgets.
|
|
|
+
|
|
|
+5. Value structs:
|
|
|
+ - `GdkRectangle` (four `int`) likely matches V3 tight records;
|
|
|
+ - `GdkRGBA` (four `gfloat`) does not until float32 is fixed;
|
|
|
+ - `GValue` is 24 bytes and may match;
|
|
|
+ - `GtkTreeIter`, `PangoRectangle`, Graphene records need layout
|
|
|
+ audits.
|
|
|
+
|
|
|
+6. `GError**`, `GValue` and property APIs need C helpers or explicit
|
|
|
+ wrapper conventions.
|
|
|
+
|
|
|
+7. `gir2def.py` is intentionally coarse: value structs become opaque
|
|
|
+ `ADDRESS`, `GError**` and varargs are dropped, and signals/properties
|
|
|
+ are not generated. It is a bootstrap tool, not a complete GTK API.
|
|
|
+
|
|
|
+8. GTK needs `pkg-config gtk4`, `-pthread`, optional libadwaita /
|
|
|
+ GtkSourceView / libspelling / libpanel, and multiple C shims.
|
|
|
+ V3's `M2make` currently supports only one extra C file and links
|
|
|
+ `-lm` only.
|
|
|
+
|
|
|
+### 15.4 Reuse plan
|
|
|
+
|
|
|
+Directly reusable:
|
|
|
+
|
|
|
+- SQLite `.def` and `SQLiteUtils` as the first port;
|
|
|
+- SDL3 video/render/events/rect/key definitions and test/style;
|
|
|
+- GTK `GtkClosures`, `GtkUtils` design and `m2gtkshim.c`;
|
|
|
+- GIR generator/verifier after adapting V3 type mapping;
|
|
|
+- examples/tests as acceptance tests.
|
|
|
+
|
|
|
+Not directly reusable:
|
|
|
+
|
|
|
+- gm2-specific `[ T ]` result syntax without a V3 parser addition;
|
|
|
+- `...` varargs declarations without wrappers;
|
|
|
+- gm2's 4-byte `SHORTREAL` assumption;
|
|
|
+- gm2's C bool/string ABI assumptions;
|
|
|
+- value structs whose layout depends on C padding/alignment;
|
|
|
+- one `--extra` C file build model.
|
|
|
+
|
|
|
+### 15.5 Porting order
|
|
|
+
|
|
|
+1. V3 C FFI foundation:
|
|
|
+ - foreign `char *` / buffer ABI;
|
|
|
+ - true `SHORTREAL`/`REAL32`;
|
|
|
+ - C `bool`;
|
|
|
+ - `[ T ]` or stripped definitions;
|
|
|
+ - varargs wrapper strategy;
|
|
|
+ - `EXTERNAL "c_name"` and long names;
|
|
|
+ - `pkg-config` build integration.
|
|
|
+2. Port SQLite:
|
|
|
+ - `SQLite.def` + `SQLiteUtils`;
|
|
|
+ - in-memory tests;
|
|
|
+ - callback tests;
|
|
|
+ - blob/bind/column tests.
|
|
|
+3. Port SDL3:
|
|
|
+ - fix float/bool/string ABI;
|
|
|
+ - keep the event-buffer design or replace with a C decoder;
|
|
|
+ - dummy-driver tests.
|
|
|
+4. Port a small GTK4 subset:
|
|
|
+ - `GLib`, `GObject`, `Gio`, `GtkApplication`, `GtkWindow`,
|
|
|
+ `GtkButton`, `GtkLabel`, `GtkBox`;
|
|
|
+ - port `GtkUtils`, `GtkClosures`, `m2gtkshim.c`;
|
|
|
+ - add a few tests and examples;
|
|
|
+ - expand via GIR.
|
|
|
+5. Keep SDL2 separate; do not mix SDL2 and SDL3 bindings.
|
|
|
+6. Put bindings outside the compiler core:
|
|
|
+
|
|
|
+ ```text
|
|
|
+ bindings/sqlite3/
|
|
|
+ bindings/sdl3/
|
|
|
+ bindings/gtk4/
|
|
|
+ ```
|
|
|
+
|
|
|
+ Each package owns its `.def`/`.mod`, C shim, tests, examples,
|
|
|
+ license/provenance and V3 build manifest.
|
|
|
+
|
|
|
+Do not vendor upstream GTK/SDL/SQLite source trees into V3; keep them
|
|
|
+as read-only references or system packages.
|
|
|
+
|
|
|
+### 15.6 Assessment
|
|
|
+
|
|
|
+- `m2SQLITE`: best first target, but string ABI is a prerequisite.
|
|
|
+- `m2SDL3`: solid second target after float32, C bool and string ABI.
|
|
|
+- `m2-GTK4`: excellent long-term asset; do not port all 432 modules
|
|
|
+ before the FFI/parser work.
|
|
|
+
|
|
|
+The efficient route is: fix the C FFI, port SQLite, port SDL3, then port
|
|
|
+a small GTK4 subset using the existing closure/shim architecture.
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 16. Suggested order of future work
|
|
|
|
|
|
1. `TBITSIZE` (small, standard-facing).
|
|
|
2. `ADDADR`/`SUBADR`/`DIFADR` (small, ISO SYSTEM).
|
|
|
@@ -2147,14 +2393,16 @@ bindings/gtk4/ GLib/GObject/GTK4 bindings
|
|
|
9. C FFI foundation and bindings: underscore policy, link names,
|
|
|
float32, size_t, C strings/buffers, struct/callback wrappers,
|
|
|
pkg-config; SQLite, then SDL3, then GTK4.
|
|
|
-10. Communications: `Serial`/`Transport` first; protocols and terminal
|
|
|
+10. Port the existing gm2 bindings: SQLite first, SDL3 second, GTK4
|
|
|
+ subset last; keep them as separate `bindings/` packages.
|
|
|
+11. Communications: `Serial`/`Transport` first; protocols and terminal
|
|
|
emulation optional.
|
|
|
-11. Network: `Net`/`Transport`, TCP/UDP, `Poll`, then optional TLS/HTTP.
|
|
|
-12. Database: SQLite binding or typed B-tree table layer; dBase III
|
|
|
+12. Network: `Net`/`Transport`, TCP/UDP, `Poll`, then optional TLS/HTTP.
|
|
|
+13. Database: SQLite binding or typed B-tree table layer; dBase III
|
|
|
only if required.
|
|
|
-13. ISO `COROUTINES` subset, then interrupt/protection layer.
|
|
|
-14. Dynamic `SET CONST` and deep composite copies.
|
|
|
-15. Parser error recovery and diagnostics.
|
|
|
+14. ISO `COROUTINES` subset, then interrupt/protection layer.
|
|
|
+15. Dynamic `SET CONST` and deep composite copies.
|
|
|
+16. Parser error recovery and diagnostics.
|
|
|
|
|
|
External assembly needs no compiler work; document it as the supported
|
|
|
low-level escape hatch.
|
