M2compiler-V3/docs/c-binding-compiler-notes.md

C binding compiler notes

Date: 2026-10-27

These notes record compiler-side decisions and fixes driven by the V3 SQLite binding.

Long string literals

The previous compiler path truncated string literals during lowering because LowerExprFull and LowerBuiltinExpr copied the AST text into SymTab.Name (64 chars). Fixed in compiler/src/Lower.mod by using a 255-byte literal buffer.

Covered by:

compiler/tests/t_longstr.mod

The practical limit is still set by the scanner/grammar buffers and AST.MaxTxtLen (255). Keep very large SQL scripts below that limit or build them through a character buffer.

C scalar widths and pointer sentinels

SYSTEM.CSIZE_T and SYSTEM.CSSIZE_T now use the 64-bit integer representation on the supported amd64 target. This matches C size_t/ssize_t; SYSTEM.COFF_T was already 64-bit.

Covered by:

compiler/tests/t_csize.mod

VAL(ADDRESS, integer) now supports pointer sentinels such as:

p := VAL(ADDRESS, -1);

Covered by:

compiler/tests/t_ptrsentinel.mod

ADR on arrays

Current behavior:

ADR(fixedArray)       (* descriptor address *)
ADR(fixedArray[0])    (* first data byte *)
ADR(openArray)        (* payload base for a view *)
ADR(multiDimArray)    (* payload base for the generated view *)

Decision: keep the existing ADR semantics and use:

ADR(a[0])

when passing a fixed character array to C as a data pointer.

Changing ADR(a) globally to mean the data address would also change pointer-to-array indexing (p := ADR(a); p^[i]), which currently relies on the descriptor representation. A separate data-address intrinsic was prototyped but not landed in this slice; the C-binding convention remains ADR(a[0]).

EXPORT placement

The definition-module grammar requires the export list before declaration blocks. Placing TYPE/CONST/VAR before EXPORT now produces the specific diagnostic:

EXPORT must precede declarations

Covered by:

compiler/tests/d_bad_export_order.mod

The parser could be made permissive, but the obvious grammar change introduced significant parser/graph complexity, so the compiler now diagnoses the invalid ordering clearly instead.