# tools — GIR → Modula-2 binding generator

`gir2def.py` is the optional, broad-coverage companion to the hand-written
bindings in `src/`. It reads a GObject-Introspection `.gir` file and emits
`DEFINITION MODULE FOR "C"` `.def` files that link straight against the C
library.

## Usage

```sh
make gir                       # Gtk-4.0 -> gen/
make gir GIR=Gio-2.0           # another namespace
make gir-check                 # generate + parse all + compile/link a sample
make gir-verify                # check every identifier exists in the .so

# or directly
python3 tools/gir2def.py Gtk-4.0 -o gen
python3 tools/gir2def.py Adw-1 -o gen
python3 tools/gir_verify.py Adw-1 --gir-dir /usr/share/gir-1.0
```

`.gir` files ship with the introspection data, typically
`/usr/share/gir-1.0/<Namespace>-<Version>.gir`.

Output goes to `gen/` (git-ignored). Generated files are meant to be
**reviewed and cherry-picked**, not to replace `src/`.

## What it produces

For `Gtk-4.0` it currently emits 301 type modules, 3719 procedures and
750 enum constants; for `GLib-2.0`, `Gio-2.0` and `Adw-1`, 77 / 168 / 83
modules. Every emitted module parses under `gm2 -fiso` (`make gir-check`,
which bulk-imports all of them and links a sample), and `make gir-verify`
confirms every identifier exists in the installed library:

| namespace | identifiers | unexpected missing |
|---|---|---|
| Gtk-4.0 | 3719 | 0 |
| GLib-2.0 | 1825 | 0 |
| Gio-2.0 | 1870 | 0 |
| Adw-1 | 1188 | 0 |

`gir_verify.py` strips symbol-version suffixes (`@@LIBADWAITA_1_0`) and
consults `gir_verify_allowlist.txt`, which lists the handful of GIR
entries that are macros, deprecated no-ops or per-module ABI functions
rather than exported symbols.

* One module per class/interface/record/boxed, named
  `<Namespace><Name>` (`GtkButton`, ...), with a `TYPE <C type> = ADDRESS;`
  alias.
* Constructors, methods and functions from that type. The procedure name
  is the GIR `c:identifier`, so no name mangling is needed.
* Namespace-level functions in `<Namespace>Functions.def`.
* Enumerations and bitfields in `<Namespace>Enums.def`, named by their
  `c:identifier` (e.g. `GTK_ALIGN_FILL`).

Example (`gen/GtkButton.def`):

```modula2
DEFINITION MODULE FOR "C" GtkButton ;

FROM SYSTEM IMPORT ADDRESS;

EXPORT UNQUALIFIED
   GtkButton, gtk_button_new, gtk_button_new_with_label,
   gtk_button_get_label, gtk_button_set_label;

TYPE
   GtkButton = ADDRESS;

PROCEDURE gtk_button_new () : [ ADDRESS ];
PROCEDURE gtk_button_new_with_label (label: ARRAY OF CHAR) : [ ADDRESS ];
PROCEDURE gtk_button_get_label (button: GtkButton) : [ ADDRESS ];
PROCEDURE gtk_button_set_label (button: GtkButton; label: ARRAY OF CHAR);

END GtkButton.
```

## Type mapping

| GIR | Modula-2 |
|---|---|
| `gboolean`, `gint*`, `int`, `gshort` | `INTEGER` |
| `guint*`, `unsigned int`, `gunichar` | `CARDINAL` |
| `glong`, `gint64`, `gssize`, `goffset` | `LONGINT` |
| `gulong`, `guint64`, `gsize`, `GType` | `LONGCARD` |
| `gchar`, `guchar` | `CHAR` |
| `gfloat`, `float` | `SHORTREAL` |
| `gdouble`, `double` | `REAL` |
| `utf8` / `filename` (in) | `ARRAY OF CHAR` |
| `utf8` / `filename` (out, return) | `ADDRESS` |
| enumeration / bitfield | `CARDINAL` |
| arrays, pointers, callbacks, unknown | `ADDRESS` |
| `out` / `inout` scalar | `VAR <type>` |

Return values are always emitted as ignorable, `: [ T ]`.

## Limits (why it is a starting point, not a re-placement)

* Value structs (by-value records such as `GdkRGBA`) become opaque
  `ADDRESS`; only pointer semantics are correct.
* Signals, properties, and `GObject` class/interface hierarchies are not
  emitted.
* Variadic functions and `GError **` parameters are dropped.
* Callbacks are `ADDRESS`; use them with `GtkClosures.Connect3` by hand.
* Constructors return `ADDRESS` for foreign types, so you may want to
  hand-edit those to the owning type name.
* No `[ ]`/`VAR` heuristics beyond the ones above.

The hand-written modules in `src/` remain the idiomatic API; the generator
is there to bootstrap areas not covered by hand.