# 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:

```text
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:

```text
compiler/tests/t_csize.mod
```

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

```modula2
p := VAL(ADDRESS, -1);
```

Covered by:

```text
compiler/tests/t_ptrsentinel.mod
```

## `ADR` on arrays

Current behavior:

```modula2
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:

```modula2
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:

```text
EXPORT must precede declarations
```

Covered by:

```text
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.