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 #for stopped 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):

DirectiveTypeDescription
@osstr"windows", "linux", "macos"
@archstr"x86_64", "aarch64"
@debugbooltrue if -g flag passed
@opti64Optimization 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:

DirectiveUsage
@c_include("header.h")Emit #include in generated C
@c_abiMark 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:

DirectiveEffect
@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:

NameDescription
tccBundled TCC (default on Windows) — fast, no optimization
clangLLVM Clang — must be on PATH or installed with Visual Studio
gccGCC/MinGW — must be on PATH
ccSystem default (default on macOS/Linux)
Full pathAny 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")
}
ValueEffect
"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=ON errors 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("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.