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.

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 includes 28 tests (feature tests and error tests), displayed in a colored table.

Check Version

./build/GX --version