Overview

GX is a procedural, statically-typed programming language inspired by C.
It compiles through a pluggable backend architecture, with two native backends: C transpiler (default) and LLVM IR (--backend llvm).

Design Goals

• Deterministic behavior
• Zero hidden allocations
• C-compatible layout and ABI
• UTF-8 native strings
• Clean and predictable syntax
• Direct interoperability with C libraries
• Pluggable backends for different targets

Non-Goals

• No borrow checker
• No hidden runtime
• No garbage collector
• No inheritance-based OOP

GX assumes the programmer is responsible and values clarity over cleverness.

Compilation Model

GX Source → Frontend (Lex/Parse/Resolve/TypeCheck) → Backend → Output

Two production pipelines:

GX → C → Native executable          (C backend, default — GX → .c → TCC/clang/gcc)
GX → LLVM IR → Native executable    (LLVM backend — GX → .ll + user_glue.c → clang)

The compiler’s frontend and backend are cleanly separated. The frontend produces a resolved, typed AST. The backend consumes it through a pluggable Backend interface. Switch backends via --backend c (default) or --backend llvm.

C Transpiler (default): generates portable, readable C code. Best for integration with existing C toolchains, fast incremental builds via bundled TCC, and portability.

LLVM IR: emits textual LLVM IR plus a tiny generated user_glue.c with shim wrappers for any extern fn, then invokes clang to link. Aligned feature set with the C backend (vectors, matrices, arrays, maps, strings, unions, modules, allocators, defer, comptime, extern C interop). Ships against the same module corpus.

Future backends: interpreter, GPU compute shaders.

Standard Modules

GX ships with reusable modules in the modules/ directory:

• math — Scalar math (trig, sqrt, clamp, lerp), vector utilities (length, normalize, distance), and matrix transforms (perspective, look_at, multiply). See 07_Math_Module.
• io / random / time — File I/O, PRNG + simplex noise, clock/date/sleep.
• json / xml — yyjson-backed JSON, ezxml-backed XML.
• raylib — Raylib bindings (graphics / input / audio). See 11_Raylib_Module.
• sokol — Bindings for Sokol graphics/app/input libraries. See 17_Sokol_Module.
• clay — Clay UI layout, with raylib and sokol renderer adapters.
• microaudio — Audio playback. See 20_Microaudio_Module.
• enet — UDP networking via lsalzman/enet 1.3.18 (new in v0.8.3).
• threading — Win32 / pthread threads + atomics (new in v0.8.3).
• sdl3 — SDL 3.2.18: window, events, renderer (new in v0.8.3).
• cimgui — Dear ImGui v1.92.7 via cimgui (new in v0.8.3).

Import with import math.scalar, import math.vec, import math.mat. See What’s New in v0.8.3 for the latest module additions and compiler changes.

Architecture

src/
  frontend/       Lexer, Parser, Resolver, Type Checker, Module Loader, Comptime
  backend/c/      C transpiler + C compiler invocation
  backend/llvm/   LLVM IR codegen + clang invocation
  driver/         CLI argument parsing
include/gx/
  backend/        Abstract Backend interface (backend.h)
  llvm_codegen.h  LLVM codegen class
  version.h       Single-source version definition
runtime/
  gx_runtime.h    Shared runtime (ec_str, ec_array, ec_map, etc.)
  gx_runtime_glue.c Linker-visible copies for the LLVM backend
modules/
  math/gx/        Math module (scalar, vec, mat)
  io/gx/          File I/O, filesystem, paths
  random/gx/      PRNG and simplex noise
  time/gx/        Clock, date/time, sleep
  json/gx/        JSON parsing / building (yyjson-backed)
  xml/gx/         XML parsing
  clay/           Clay UI layout
  raylib/         Raylib bindings
  sokol/          Sokol bindings (app, gfx, glue, gp)
  microaudio/     Audio playback
  enet/           UDP networking (v0.8.3)
  threading/      Threads + atomics (v0.8.3)
  sdl3/           SDL3 window/events/renderer (v0.8.3)
  cimgui/         Dear ImGui via cimgui (v0.8.3)

Versioning

GX follows Semantic Versioning. The version is defined once in include/gx/version.h and propagated to all compiler output and generated code automatically.