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=llvm on a GX built without -DGX_ENABLE_LLVM=ON errors with a precise rebuild instruction — and also points at --backend=llvm-clang as 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 / @cppfile sources. 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; -O2 and -g builds 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\obj on Windows, ~/Library/Caches/gx/cache/obj on macOS, ~/.cache/gx/cache/obj on Linux; GX_OBJ_CACHE_DIR overrides it. Entries unused for 30 days are removed once the cache grows large.
  • gx doctor shows its size, gx doctor --clear-obj-cache empties it, --no-obj-cache (or GX_OBJ_CACHE=0) bypasses it for one build, and --verbose prints a hit or miss line 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 under modules/). The recipe is read from the module’s .gx files, so there is nothing to configure.
  • The library is always the optimized build, also in a -g or -O0 build of your program, and it is not affected by -D defines 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>_LIB line from overrides.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