Compile-Time System
GX supports compile-time evaluation — code that runs during compilation, not at runtime. The result is zero-overhead: the C compiler sees only flat, fully-resolved code.
Two prefixes mark compile-time features:
#— Compile-time constructs (control flow that executes during compilation)@— Compile-time directives (annotations, queries, and metadata for the compiler)
# — Compile-Time Constructs
#if / #else — Compile-Time Conditional
Evaluates a condition at compile time. The dead branch is removed entirely — the resolver never sees it.
// Declaration-level (top-level)
#if (@os == "windows") {
const PLATFORM = "Windows";
} #else {
const PLATFORM = "Other";
}
// Statement-level (inside functions)
fn init() {
#if (@os == "windows") {
init_win32();
} #else {
init_posix();
}
}
// Inside struct bodies — conditional fields
struct Connection {
id: i32
#if (@os == "windows") {
handle: i64
} #else {
fd: i32
}
}
// Inside enum bodies — conditional members
enum LogLevel {
Error
Warning
Info
#if (@debug) {
Debug
Trace
}
}
#for — Compile-Time Loop (Unrolling)
Unrolls a loop at compile time. Uses the same syntax as GX’s for-range (var=start:end), with the same meaning: the range is inclusive on both ends, so #for (i=0:3) runs for 0, 1, 2 and 3. Each iteration is stamped as separate statements — zero runtime loop overhead.
// Statement-level
#for (i=0:3) {
print("channel {i}");
}
// Unrolls to:
// print("channel 0");
// print("channel 1");
// print("channel 2");
// print("channel 3");
// Inside struct bodies — generated fields with name interpolation
struct Pixel {
#for (i=0:3) {
channel_i: f32
}
}
// Produces: struct Pixel { float channel_0; float channel_1; float channel_2; float channel_3; };
// Nested #for — 3 x 3 = 9 prints, (0,0) through (2,2)
#for (row=0:2) {
#for (col=0:2) {
print("({row},{col})");
}
}
// Const bounds — bit 0 through bit 7
const N = 8;
#for (i=0:N - 1) {
print("bit {i}");
}
Changed in v0.8.7. Before 0.8.7
#forstopped one short of the upper bound, so the same range syntax meant two different things at compile time and at run time. A loop that counts up to a size now needs- 1(#for (i=0:N - 1),#for (i=0:@fields(T) - 1)). A loop that was not updated walks one index past the end, which the reflection intrinsics report as an error (@field index 3 out of range (0..2)), so stale code fails loudly.
#fn — Compile-Time Function
Defines a function that runs entirely at compile time. Called from const initializers to compute values during compilation.
#fn align_up:i32(size:i32, align:i32) {
return (size + align - 1) & ~(align - 1);
}
#fn fib:i32(n:i32) {
if (n <= 1) { return n; }
return fib(n - 1) + fib(n - 2);
}
const BUF_SIZE = align_up(100, 64); // 128 — computed at compile time
const FIB_10 = fib(10); // 55 — computed at compile time
Supports: local variables, if/else, while loops, recursion, arithmetic, comparisons, casts. No I/O, no pointers, no runtime calls.
#type — Compile-Time Type Parameter
Declares a type parameter for monomorphized generics.
#type T
struct List {
data: *T
len: i32
cap: i32
}
var nums: List<i32> // generates List_i32 struct
var names: List<str> // generates List_str struct
@ — Compile-Time Directives
The @ prefix marks compiler directives — annotations, platform queries, type reflection, and build configuration. None produce runtime code. An unknown directive (@bogus) is a compile error.
Platform & Build Info
Available everywhere (including #if conditions):
| Directive | Type | Description |
|---|---|---|
@os | str | "windows", "linux", "macos" |
@arch | str | "x86_64", "aarch64" |
@debug | bool | true if -g flag passed |
@opt | i64 | Optimization level (0-3) |
#if (@os == "windows" && @arch == "x86_64") {
// Windows x64 specific code
}
C Interop Annotations
Control how GX types and functions map to C:
| Directive | Usage |
|---|---|
@c_include("header.h") | Emit #include in generated C |
@c_abi | Mark function as C ABI callable |
@c_prefix("PREFIX_") | Map enum member names with prefix |
@c_name("exact_name") | Override C name for an enum member |
See 05_C_Interop.md for details.
Build Directives
Make .gx files self-contained — no CLI flags needed for linking or compilation:
| Directive | Effect |
|---|---|
@link("lib") | Add -llib to linker command |
@cflags("...") | Add flags to C compiler |
@ldflags("...") | Add flags to linker |
@cfile("path.c") | Compile a C source file alongside the GX output |
@cppfile("path.cpp") | Compile a C++ source file (.cpp / .cxx / .cc) alongside the GX output |
@compiler("name") | Set the C compiler (overridden by --cc) |
@backend("name") | Select the backend: "c", "llvm" (native LLVM API), "llvm-clang" (text emitter), "llvm-api" (alias for "llvm"), or "js" (overridden by --backend) |
@cfile — Include C Source Files
Compiles a C file as part of the build. Path is resolved relative to the .gx
file containing the directive. Used for single-file C libraries:
@cfile("../c/sokol_impl.c")
@cflags("-Imodules/sokol/c")
@cppfile — Include C++ Source Files
Compiles a C++ source file alongside the GX output. clang dispatches by file
extension (.cpp / .cxx / .cc), so a single compile command handles
mixed C and C++ sources. Used to bind C++ libraries that ship a C wrapper
(cimgui over imgui, etc):
@compiler("clang") // TCC can't compile C++; force clang
@cppfile("../c/imgui/imgui.cpp")
@cppfile("../c/cimgui.cpp")
@c_include("cimgui.h")
Path resolution mirrors @cfile. Presence of any @cppfile directive
forces a clang-capable compiler — TCC and bare gcc-without-g++ are
overridden automatically.
@compiler — Set the C Compiler
Sets which C compiler to use. Accepts a short name (clang, gcc) or a full
path. The --cc CLI flag always takes priority over @compiler.
#if (@os == "windows") {
@compiler("clang")
}
Recognized compiler names:
| Name | Description |
|---|---|
tcc | Bundled TCC (default on Windows) — fast, no optimization |
clang | LLVM Clang — must be on PATH or installed with Visual Studio |
gcc | GCC/MinGW — must be on PATH |
cc | System default (default on macOS/Linux) |
| Full path | Any C compiler, e.g. "C:/raylib/w64devkit/bin/gcc.exe" |
Resolution order: --cc (CLI) > @compiler (directive) > -O1+ auto-upgrade > default (tcc/cc)
Why use it: Some modules require a specific compiler. For example, raylib
uses @compiler("clang") because TCC cannot link MSVC .lib files.
@backend — Pick the Compilation Backend
Declares which backend to use when no --backend flag is passed on the
command line. Useful when a file fundamentally needs a specific backend
(e.g. wants LLVM’s diagnostics, or targets JS-only).
@backend("llvm")
fn main() {
print("always built via LLVM unless CLI overrides")
}
| Value | Effect |
|---|---|
"c" | Default C transpiler pipeline (TCC or --cc) |
"llvm" | Native LLVM C++ API backend (-O0..-O3, DWARF). Requires GX built with -DGX_ENABLE_LLVM=ON. |
"llvm-api" | Silent alias for "llvm" — kept for back-compat. |
"llvm-clang" | Text-emitting LLVM variant. Writes .ll, shells out to clang to PARSE it back and link. Available in every build of GX. |
"js" | JavaScript transpile (emit-only, equivalent to --emit-js) |
Resolution order: --backend (CLI) > @backend (directive) > default ("c").
A file that declares
@backend("llvm")on a GX built without-DGX_ENABLE_LLVM=ONerrors with a precise rebuild instruction — and also points at"llvm-clang"as the no-rebuild alternative.
Unknown values produce a warning and the compiler falls back to the default.
If multiple @backend directives appear (e.g. across imported modules),
the last one wins — prefer declaring it in the main .gx file only.
@link, @cflags, @ldflags — Linking and Flags
@link("opengl32")
#if (@os == "windows") {
@link("user32")
@link("gdi32")
} #else {
@ldflags("-lX11 -lGL")
}
@c_include("sokol_app.h")
All build directives compose with #if for platform-conditional builds. They propagate across module imports — import sokol.app inherits its @link flags automatically.
Reflection Introspection
Compile-time access to type metadata:
Struct / Union fields:
@fields(T) — field count (i64)
@field(T, i) — field name at index i (str)
@field_type(T, i) — field type name (str)
@field_is_ptr(T, i) — is pointer? (bool)
@field_is_array(T, i) — is fixed array? (bool)
Reflection gives names and types. There is no way to read a field’s value
by index (obj.@field(i) is not supported); access fields by name.
Enum members:
@members(E) — member count (i64)
@member(E, i) — member name at index i (str)
Function params:
@params(F) — parameter count (i64)
@param(F, i) — parameter name (str)
@param_type(F, i) — parameter type name (str)
@return_type(F) — return type name (str)
Type meta:
@type_name(T) — type name as string
@type_kind(T) — "struct" / "enum" / "union" / "builtin"
The counts combine with #for to visit every member. Indices run from 0
to count - 1, and #for is inclusive, so the upper bound is count - 1:
struct Point { x:f32 y:f32 z:f32 }
fn main() {
print("Point has {@fields(Point)} fields:\n");
#for (i=0:@fields(Point) - 1) {
print(" {@field(Point, i)}: {@field_type(Point, i)}\n");
}
}
// Point has 3 fields:
// x: f32
// y: f32
// z: f32
Pipeline
Compile-time evaluation happens at two points in the compilation pipeline:
Lexer → Parser → pre_pass → Resolver → Type Checker → post_pass → C Transpiler
↑ ↑
#if (declaration-level) #if (statement-level)
#for (struct fields) #for (loop unrolling)
@link collection @fields / @field evaluation
Pre-pass (before resolution): Evaluates #if at declaration level, expands struct/enum compile-time constructs, collects build directives. Only built-in @ variables are available.
Post-pass (after type checking): Evaluates #if at statement level, unrolls #for loops, evaluates reflection intrinsics. User const values and type info are available.