Getting Started
IDE Support
GX has a dedicated IntelliJ-GX plugin for JetBrains IDEs (IntelliJ IDEA, CLion, etc.):
- Syntax highlighting for all keywords including compile-time (
#if,#for,#fn,#type,@fields,@link, etc.) - Code completion and navigation (go-to definition, find usages)
- Debugger integration
- Error highlighting
Install from Settings > Plugins > Marketplace and search for “GX Language”.
Requirements
- C++20 compiler (for building the GX compiler)
- CMake 3.15+
- C compiler (clang, gcc, or MSVC — used by GX at runtime)
macOS
Xcode Command Line Tools is the only real dependency — it provides the C/C++ compiler, linker, and all macOS frameworks needed for GX and the Sokol graphics demos:
# 1. Install Xcode Command Line Tools (the only real dependency)
xcode-select --install
# 2. Install CMake (needed only to build the GX compiler itself)
brew install cmake
Windows
- Visual Studio 2019+ with “Desktop development with C++” workload
- CMake 3.15+ (download)
Linux
# Ubuntu / Debian
sudo apt install build-essential cmake
# Fedora
sudo dnf install gcc-c++ cmake
Build GX
macOS / Linux
cmake -B build
cmake --build build
The compiler executable GX will be in build/.
Windows
cmake -S . -B build -G "Visual Studio 17 2022"
cmake --build build --config Release
The compiler executable GX.exe will be in build/Release/.
Optional: LLVM-enabled build
The default build above gives you --backend=c (C transpiler, the
default) and --backend=llvm-clang (text-emitting LLVM, which shells
out to a clang binary at runtime). Both work without an LLVM
development install.
For --backend=llvm — the native LLVM C++ API backend with
-O0..-O3 optimisation and DWARF debug info — GX needs to link
libLLVM itself. Build a separate tree with the option turned on:
# Requires an LLVM development install (headers + libs) discoverable
# by CMake. Conda-forge's `llvmdev` package works; system LLVM packages
# (`apt install llvm-dev`, `brew install llvm`, etc.) also work as long
# as you point CMake at their `lib/cmake/llvm` directory.
cmake -S . -B build-llvm -DGX_ENABLE_LLVM=ON \
-DLLVM_DIR=/path/to/llvm/lib/cmake/llvm
cmake --build build-llvm --config Release
The default build/ tree stays zero-dependency; build-llvm/Release/GX.exe
(or build-llvm/GX on POSIX) is the LLVM-enabled compiler. On a default
build, --backend=llvm errors out cleanly with this rebuild instruction.
Hello World
fn main() {
print("Hello, GX!\n")
}
Run:
# macOS / Linux
./build/GX run hello.gx
# Windows
build\Release\GX.exe run hello.gx
Or generate C only:
./build/GX hello.gx -S -o hello.c
Picking a Backend
GX ships with three native backends — pick per-invocation on the CLI, or declare the choice in the source file itself.
# Default: C backend (bundled TCC, fast, zero-dependency)
gx hello.gx -o hello
# Native LLVM C++ API backend (requires the LLVM-enabled build above)
gx hello.gx --backend=llvm -o hello
# Text-emitting LLVM variant (writes .ll, shells to clang to link)
# Available in every build of GX; needs only a `clang` binary at runtime.
gx hello.gx --backend=llvm-clang -o hello
# Inspect intermediate output
gx hello.gx -S # emits hello.gx.c
gx hello.gx --backend=llvm -S # emits hello.gx.api.ll (post-opt)
gx hello.gx --backend=llvm-clang -S # emits hello.gx.ll
--backend=llvm-api remains a silent alias for --backend=llvm.
The native llvm backend has two big advantages over the text-emitting
variant: it runs LLVM’s full -O1/-O2/-O3 pipeline on the IR in
process, and it emits DWARF debug info under -g (line tables plus
dbg.declare for every local and parameter, so lldb / gdb can step
the program and print variables). It does require GX itself to be
built with -DGX_ENABLE_LLVM=ON — see “Optional: LLVM-enabled build”
above.
Or lock a file to a specific backend with the @backend directive:
// hello.gx
@backend("llvm")
fn main() {
print("always built via the native LLVM backend\n")
}
Then gx hello.gx -o hello picks the native LLVM backend automatically.
The CLI flag overrides the directive when both are present (same pattern
as @compiler vs --cc).
Note:
--backend=llvmon a GX built without-DGX_ENABLE_LLVM=ONerrors with a precise rebuild instruction — and also points at--backend=llvm-clangas the no-rebuild alternative. The default C backend ships with TCC bundled and has no external dependencies.
Build Times: the Object Cache
A program that imports a C-backed module (sokol, cimgui, json, …)
needs that module’s C or C++ sources compiled. GX compiles each such source
to an object file once and links the cached object afterwards, so only
your own code is compiled on the following builds. A program using Dear
ImGui on sokol builds in under a second after the first time, instead of
several seconds every time; on the first build the sources compile in
parallel.
- It applies to every module, to modules added later, and to your own
@cfile/@cppfilesources. Nothing has to be set up. - An entry is reused only while the source and every header it includes are
unchanged, and only for the same compiler and the same flags. Editing a
header recompiles exactly the sources that include it;
-O2and-gbuilds have their own entries. - It is used with clang and gcc (so with
-O1+,-g, C++ modules and both LLVM backends). The bundled TCC is not cached: it is fast enough already. - Location:
%LOCALAPPDATA%\gx\cache\objon Windows,~/Library/Caches/gx/cache/objon macOS,~/.cache/gx/cache/objon Linux;GX_OBJ_CACHE_DIRoverrides it. Entries unused for 30 days are removed once the cache grows large. gx doctorshows its size,gx doctor --clear-obj-cacheempties it,--no-obj-cache(orGX_OBJ_CACHE=0) bypasses it for one build, and--verboseprints ahitormissline per source.
Prebuilt Module Libraries
The object cache needs nothing from you. If you want a module out of the build completely, build it into a static library once:
gx doctor --rebuild cimgui --use # one module
gx doctor --rebuild all --use # every module that ships C / C++ sources
This compiles the module’s sources at -O2, archives them as
lib<module>.a in the per-user cache (<cache>/<module>-<gx version>/) and,
with --use, records the archive as GX_<MODULE>_LIB in overrides.env.
From then on a program that imports the module links the archive and compiles
none of its sources: --verbose prints a Prebuilt module: line instead of
the obj cache: lines.
- It works for every module that names its sources with
@cfile/@cppfile(sokol,cimgui,cimgui_sokol,cimgui_raylib,json,xml,enet,clay,threading, and your own modules undermodules/). The recipe is read from the module’s.gxfiles, so there is nothing to configure. - The library is always the optimized build, also in a
-gor-O0build of your program, and it is not affected by-Ddefines on the command line. That is the difference from the object cache, which keeps one entry per flag set. - It is skipped, and the sources are compiled as usual, when the archive is
missing (each GX version has its own archive directory, so re-run the
command after an upgrade), when a file under the module’s
c/directory is newer than the archive, with--no-prebuilt, with--target web, and when the bundled TCC links the program. The first two print a note. - To stop using it, remove the
GX_<MODULE>_LIBline fromoverrides.env.
On build time the two are close: with a warm object cache a Dear ImGui + sokol program already builds in under a second, and the prebuilt library gives the same. The library pays off when you switch flags often (each flag set would otherwise compile the module once more) and when you want optimized module code inside a debug build.
Run Examples
bash run_examples.sh # macOS / Linux
run_examples.bat # Windows
All example binaries are output to build/ to keep the examples folder clean.
Sokol Graphics Demos (macOS)
Graphical demos using Sokol have dedicated run scripts:
bash run_triangle.sh # Sokol triangle rendering
bash run_shapes.sh # Sokol GP shapes demo
bash run_snake.sh # Snake game
bash run_input.sh # Sokol input handling demo
These link against macOS-native frameworks (Metal, Cocoa, OpenGL) and are macOS-only for now.
Run Tests
bash tests/run_tests.sh
The test suite has 70 tests (feature tests and error tests), displayed in a colored table. The same suite passes on all three native backends:
bash tests/run_tests.sh --backend llvm-clang
bash tests/run_tests.sh --backend llvm --native # needs an LLVM-enabled build
Check Version
./build/GX --version