C Interop
GX is designed for seamless C integration.
Include C Headers
@c_include("stdio.h")
Extern Functions
extern fn printf:c_int(fmt:cstr, ...)
A variadic extern (...) checks its fixed parameters and passes the extra
arguments through. A str passed for %s is lowered to its pointer:
var n = 3
var name = "items"
printf("%d %s\n", n, name)
ABI Types
c_int, c_uint, c_long, c_ulong
c_size, c_ssize
c_char, c_uchar
c_bool, c_void
cstr (raw const char* — auto-converts to/from str, see cstr and str)
cstr and str
str is GX’s fat string (pointer plus length); cstr is a bare
NUL-terminated const char*. The compiler converts between them:
str→cstr: passing astrto anextern fnparameter of typecstrpasses its pointercstr→str: acstris accepted where astris expected in arguments, variable initializers and assignments
@c_include("string.h")
extern fn strstr:cstr(hay: cstr, needle: cstr)
struct Named { name: str }
fn shout:str(s: str) { return s.upper() }
fn main() {
var c: cstr = strstr("hello world", "world")
var s: str = c // initializer
var n: Named
n.name = c // assignment
print("{s} {s.len} {n.name} {shout(c)}\n") // argument: world 5 world WORLD
}
The cstr is wrapped (pointer plus strlen), not copied, so the str is
valid for as long as the C string is. A null cstr wraps to an empty str.
Extern Struct
extern struct sapp_desc {
width: c_int
height: c_int
}
@c_imported — Use the Header’s Definition
When the upstream C header you @c_include already defines a struct,
union, enum, or constant, mark the GX-side declaration @c_imported.
GX will type-check against your declared layout but emit no typedef or
body in the generated C — the upstream header is the single source of
truth.
This is required when the upstream uses the typedef struct _Foo {...} Foo
convention (prefixed tag), because GX’s default emission of
typedef struct Foo {...} Foo collides with it.
@c_include("enet/enet.h")
@c_imported
extern struct ENetAddress {
host: u32
port: u16
}
@c_imported
extern enum ENetEventType {
ENET_EVENT_TYPE_NONE = 0
ENET_EVENT_TYPE_CONNECT = 1
ENET_EVENT_TYPE_DISCONNECT = 2
ENET_EVENT_TYPE_RECEIVE = 3
}
@c_imported
const ENET_HOST_ANY: u32 = 0
Works on extern struct, extern union, extern enum, and top-level
const. The GX-side body still has to match the upstream layout (GX
trusts your declaration for type checking).
Function Pointers in Structs
GX supports function pointer fields inside extern struct definitions and,
since v0.8.7, inside normal struct definitions.
extern struct sapp_desc {
init_cb: fn()
frame_cb: fn()
cleanup_cb: fn()
width: c_int
height: c_int
}
Function pointer syntax:
fn()--- void functionfn:c_int()--- returns c_intfn(c_int, c_int)--- takes parametersfn(f32):f32--- takes parameters and returns a value (return type last)fn:f32(f32)--- the same type, with the return type afterfn:
Both spellings of the return type are accepted in either kind of struct. A function pointer field in a normal struct is assigned a GX function and called like a method:
struct Filter {
apply: fn(f32):f32 // return type after the parameters
cost: fn:i32(i32, i32) // return type after `fn:`
}
fn half:f32(x: f32) { return x * 0.5 }
fn add:i32(a: i32, b: i32) { return a + b }
fn main() {
var f: Filter // zero value: both pointers are null
f.apply = half
f.cost = add
print("{f.apply(8.0)} {f.cost(2, 3)}\n") // 4 5
}
Pointer Casts
(*T)expr casts a pointer to *T. T may be a built-in type
((*void)p, (*u8)p) or, since v0.8.7, a user type:
@c_include("stdlib.h")
extern fn malloc:*void(n: u64)
extern fn free(p: *void)
struct Node { value: i32 next: *Node }
fn main() {
var raw: *void = malloc(sizeof(Node))
var node: *Node = (*Node)raw // cast, followed by a name
node.next = (*Node)null // ... by null
var other: *Node = (*Node)malloc(sizeof(Node)) // ... or by a call
(*node).value = 7 // not a cast: a parenthesized dereference
free(other)
free(raw)
}
There is one restriction. A cast to a pointer to a user type must be
followed directly, on the same line, by a name, a call or null. This is
what keeps (*p).x and (*p) = v unambiguous: (*Name) followed by
anything else is read as a dereference of the variable Name. To cast a
larger expression, store it in a variable first.
Extern Enum
Bind to existing C enums defined in headers.
@c_prefix("SAPP_")
extern enum sapp_keycode {
KEYCODE_INVALID = 0
KEYCODE_SPACE = 32
KEYCODE_ESCAPE = 256
}
The @c_prefix("SAPP_") directive maps GX names to C names by prepending
the prefix: KEYCODE_SPACE → SAPP_KEYCODE_SPACE.
For members where the prefix + name doesn’t match the C name, use
@c_name to override:
@c_prefix("SAPP_")
extern enum sapp_keycode {
KEYCODE_0 = 48 @c_name("SAPP_KEYCODE_0")
KEYCODE_1 = 49 @c_name("SAPP_KEYCODE_1")
}
- Members separated by newlines (commas optional)
= valueis optional, for documentation and matching C header values@c_name("...")overrides the generated C name for individual members@c_prefix("...")applies to the entire enum
C-ABI Callable
@c_abi
fn callback() {}