G — Natural Language to C99

"You write prose. G speaks to hardware."

G is a zero-syntax systems programming language. You write human prose — "Set the first pin high and wait 500 ms" — and G compiles it deterministically to C99, to bare-metal x86-64 / ARM64 assembly, to AVR and ESP32 raw MMIO, and to OpenQASM 2.0 quantum circuits. One language, every layer of the stack.

• Status: Phase 49 Complete (Automated Release Script & v0.0.2 Push)
• Tests: 548 green, zero warnings
• License: MIT — see LICENSE
• Docs: MANUAL.md (implementation manual & phase ledger) · CHANGELOG.md · docs/rfc-0001.md

---

Architecture

                    ┌──────────────────────────────────────────────────┐
    human prose     │                 G compiler (Rust)                │
  "Set X to 5."     │                                                  │
        │           │   Lexer → Semantic Graph → HIR → Type Unification │
        ▼           │         → Ownership Gates → MIR → SSA             │
   zero syntax      │         → Optimizer (G-### diagnostics)           │
        │           └──────────────┬───────────────────────────────────┘
        ▼                          ▼
   deterministic            ┌──────────┐  ┌──────────┐  ┌──────────┐
   bit-for-bit output       │   C99    │  │  asm     │  │ OpenQASM │
                            │ Desktop  │  │ x86-64   │  │ 2.0      │
                            │ AVR MMIO │  │ ARM64    │  └──────────┘
                            │ ESP32    │  └──────────┘
                            └──────────┘

Same semantic graph, every backend — the optimizer feeds C99 for the desktop, GNU as for x86-64 / AArch64, raw MMIO for AVR and ESP32, and quantum assembly for QASM targets.

---

Quick Start (End Users)

Download the latest release from the GitHub Releases page — each zip is a complete standalone toolchain (the dist/ folder: g/gufran, cpm, apm, g-lsp, a bundled TCC, runtime/, stdlib/) built automatically for Windows, Linux, and macOS by GitHub Actions. Unzip it and run — it just works:

dist/g.exe examples/json.g --run          # Windows
dist/g.exe examples/build_script.g --run  # OS stdlib: lists files, runs tcc, prints exit codes
dist/g.exe examples/web_app.g --run       # serve http://localhost:8080 (HTTP framework in stdlib/net.g)
dist/g.exe examples/rest_api.g --run      # Smart Home REST API: JSON devices at :8080/api/devices
dist/g.exe examples/cli_tool.g --run Gufran  # CLI args + env: "Hello Gufran, your home is ..."
dist/g examples/hello.g                   # Linux/macOS (dist/g.exe -> dist/g)

Prefer to build it yourself? build_release.ps1 (Windows) and build_release.sh (Linux/macOS) regenerate dist/ from source — they compile the bundled TCC too.

dist/g.exe examples/json.g --run          # Windows
dist/g.exe examples/build_script.g --run  # OS stdlib: lists files, runs tcc, prints exit codes
dist/g.exe examples/web_app.g --run       # serve http://localhost:8080 (HTTP framework in stdlib/net.g)
dist/g.exe examples/rest_api.g --run      # Smart Home REST API: JSON devices at :8080/api/devices
dist/g.exe examples/cli_tool.g --run Gufran  # CLI args + env: "Hello Gufran, your home is ..."
dist/g examples/hello.g                   # Linux/macOS (dist/g.exe -> dist/g)

Add the folder holding g.exe to your PATH, then:

g examples/json.g --run      # compile with bundled TCC and execute
g examples/json.g --check    # pipeline + quality gates only
g examples/json.g --out json.c   # emit C99 instead
g examples/baremetal_x86.g --target baremetal-x86 --out x86.s  # raw assembly

No Rust, no Cargo, no C compiler installation required.

Releasing (publish.ps1)

publish.ps1 (repository root) is the standard way to ship a release — one command stages, commits, pushes, tags, and pushes the tag, which triggers the GitHub Actions workflow (.github/workflows/release.yml) to build the Windows / Linux / macOS bundles and attach them to a GitHub Release:

.\publish.ps1 -Version 0.0.2

It runs git add ., commits release: v0.0.2, pushes main, creates the v0.0.2 tag, and pushes the tag. Git is located automatically (PATH, the GitHub Desktop bundled git, or standard install paths), and the script refuses to run outside a git repository.

The Cardinal Package Manager

cpm (alias apm) scaffolds and drives G projects:

dist/cpm.exe init hello      # hello/cardinal.toml + hello/main.g
cd hello
..\dist\cpm.exe run          # dist/g.exe main.g --run  → "Hello from CPM"
..\dist\cpm.exe build        # dist/g.exe main.g --out build/main.c
..\dist\cpm.exe add ..\..\my_lib   # local dependencies, -I wired automatically

---

VS Code Setup

The vscode-extension/ folder (also shipped inside every release bundle as dist/vscode-extension/) contains a ready-to-use VS Code extension: syntax highlighting for .g / .gufran files plus a full language server (G-### diagnostics squiggles, autocomplete, hover, F12 goto-definition) powered by g-lsp.

Option A — Install from VSIX (recommended)

From the repo (or dist/vscode-extension):

npm install          # installs the vscode-languageclient dependency
npx @vscode/vsce package

This produces cardinal-language-1.0.0.vsix. In VS Code: Extensions → … (top-right) → Install from VSIX… and pick the file.

Option B — Copy the folder (no packaging)

Copy vscode-extension/ to the VS Code extensions directory and restart VS Code:

• Windows: %USERPROFILE%\.vscode\extensions\skgufranahmed.cardinal-language-1.0.0
• Linux/macOS: ~/.vscode/extensions/skgufranahmed.cardinal-language-1.0.0

(The folder must be named <publisher>.<name>-<version> for VS Code to load it.) Remember npm install inside it once — the extension needs vscode-languageclient.

Pointing the language server at g-lsp

The extension resolves g-lsp in this order:

1. cardinal.gLspPath setting — an absolute path to g-lsp / g-lsp.exe (highest priority; verified to exist before use).
2. System PATH — g-lsp (or g-lsp.exe on Windows), found via where/which.

If you did not add dist/ to your PATH, set the path in VS Code settings:

{
  "cardinal.gLspPath": "C:\\path\\to\\g-language\\dist\\g-lsp.exe"
}

Open any .g file and the server starts automatically (diagnostics appear on every keystroke; Ctrl+Space offers completions; hover shows types; F12 jumps to declarations).

---

Features

• Zero syntax — human prose in, no brackets, no semicolons, no end. required (implicit EOF scoping)
• Deterministic, bit-for-bit reproducible compilation
• Typed routines with recursion, records, enums (exhaustiveness-checked), ADTs (Optional/Result)
• Lists, Tables, Maps with bounds-checked indexing
• Text ops — Split, Substring, contains, followed by, Number of / Text of
• Memory safety — arena/static allocation, ownership tracking, capability lattice
• FFI to C — Import C function ... from "<shim>.h" (deduplicated includes, Phase 44.1)
• Standard Library — stdlib/net.g (TCP + HTTP framework), stdlib/math.g, stdlib/regex.g, stdlib/os.g (process execution), stdlib/fs.g, stdlib/time.g (TimeNow/Sleep, Phase 46), stdlib/strings.g (Uppercase/Lowercase/Trim/Replace, Phase 46)
• Web framework — examples/web_app.g routes /api → JSON; examples/rest_api.g (Phase 48) serves a Smart Home REST API with parameterized device routes, tables and 404 handling — both on stdlib/net.g
• --run — compile with the bundled TCC and execute; argument forwarding; child cleanup on exit
• Bare-metal x86-64 & ARM64 — syscall assembly with real stack frames ([rbp-8], [sp, 16+8N] slots, unlimited variables)
• AVR — raw MMIO (DDRB/PORTB), Timer0 CTC interrupts and INT0 ISRs (ISR(TIMER0_COMPA_vect))
• ESP32 — FreeRTOS tasks from Every <N> ms do ... verse
• Quantum — OpenQASM 2.0 output for quantum processors
• CLI & OS — Get argument count / Get argument N / Get env, List directory, File exists, Current time, RunCommand
• Self-hosted bootstrap — examples/bootstrap.g compiles and runs itself
• IDE tooling — g-lsp Language Server with completion, hover, goto-definition
• Package management — cpm/apm with cardinal.toml
• 548 tests, zero warnings, MIT licensed

---

Repository Layout

g-language/
├── .github/
│   └── workflows/
│       └── release.yml   CI/CD: push a v* tag → build Windows/Linux/macOS
│                         bundles → upload zips to the GitHub Release
├── .gitignore
├── Cargo.toml / Cargo.lock
├── LICENSE              MIT license
├── README.md            this file
├── CHANGELOG.md         the journey, Phase 1 → v1.0
├── MANUAL.md            implementation manual & phase ledger
├── build_release.ps1    regenerates dist/ from source + TCC (Windows)
├── build_release.sh     regenerates dist/ from source + TCC (Linux/macOS)
├── publish.ps1          automated release: commit + push + tag (see Releasing)
├── docs/
│   └── rfc-0001.md      grammar table & language charter
├── examples/            G programs: json.g, web_app.g, rest_api.g (REST
│                        API server), build_script.g,
│                        bootstrap.g, baremetal_*.g, and the Stage 2-5
│                        bootstrap compilers (lexer/parser/validator/codegen)
├── runtime/             g_rt.h + shims (cli, fs, math, os, regex, tcp, http,
│                        time, strings)
├── src/                 Rust compiler core (main, gufran, cpm, apm, lsp,
│                        lib, lexer, parser, hir, mir, ssa, codegen, ...)
├── stdlib/              pure-verse standard library (net.g, math.g,
│                        regex.g, os.g, fs.g, time.g, strings.g)
├── vscode-extension/    VS Code extension: package.json + extension.js
│                        (LSP client) + syntaxes/g.tmLanguage.json
├── tests/               compile.rs + e2e.rs (548 tests)
└── dist/                generated by the build scripts (git-ignored):
                         g.exe, gufran.exe, cpm.exe, apm.exe, g-lsp.exe,
                         bin/ (bundled TCC), runtime/, stdlib/,
                         vscode-extension/

---

Example Programs

examples/hello.g:

Target G Desktop.

print hello world.

Wait 100 ms.

If 2 + 2 is 4 then
    print arithmetic works.
After.

examples/json.g — a complete recursive-descent JSON parser written in pure verse (tables, enums, records, recursion):

$ target/release/g examples/json.g --run
G
true
3.5

examples/server.g — a native TCP web server (Winsock/socket FFI via runtime/tcp_shim.h, -lws2_32): serves Hello world on port 8080. examples/web_app.g / examples/api_server.g — the same server with zero FFI boilerplate through stdlib/net.g, routing /api → {"status":"ok"}.

examples/rest_api.g — a real-world REST API in pure verse (Phase 48): a Smart Home device store (Table of Text to Text) served as JSON, with parameterized device routes, on stdlib/net.g:

$ dist/g.exe examples/rest_api.g --run   # binds 127.0.0.1:8080
$ curl http://localhost:8080/api/devices
{"light":"off","thermostat":72}
$ curl http://localhost:8080/api/device/light
{"device":"light","state":"off"}
$ curl http://localhost:8080/api/device/unknown
{"error":"not found"}                     # HTTP 404
$ curl http://localhost:8080/api/bogus
{"error":"invalid route"}                 # HTTP 404

examples/build_script.g — OS standard library (Phase 44):

Target G Desktop. Import "stdlib/os.g". Import "stdlib/fs.g".
Set Files to Execute ListDir with "examples". ...

$ dist/g.exe examples/build_script.g --run
Found 29 files
TCC exists. Size: 23552 bytes
tcc version 0.9.27 (x86_64 Windows)
TCC exit code: 0

examples/system_clock.g — Time & Strings standard library (Phase 46): TimeNow stamps the start, Trim + Uppercase turn " Hello World " into HELLO WORLD, Sleep with 1000. pauses ~1 second, and the elapsed time is printed:

$ dist/g.exe examples/system_clock.g --run
Start time: 1786018036
HELLO WORLD
Elapsed: 1 seconds

examples/baremetal_x86.g — direct-to-CPU assembly (Phase 36):

Target G Baremetal x86_64.

Print "Direct to CPU".

$ g examples/baremetal_x86.g --target baremetal-x86 --out x86.s
# GNU as, SysV sys_write/sys_exit, stack-frame variables ([rbp-8], ...)

examples/baremetal_avr_isr.g — hardware interrupts (Phase 43):

Target G Baremetal avr.

Every 10 ms do Set LED on.

→ TCCR0A/TCCR0B/OCR0A/TIMSK0 Timer0 CTC config + ISR(TIMER0_COMPA_vect) with the action inside. examples/baremetal_esp32_task.g turns the same verse into a FreeRTOS task (xTaskCreate) on ESP32.

---

CLI Reference

g|gufran <file.g> [--out out.c] [--check] [--run args...]
g|gufran -g <source> [--out out.c] [--check] [--run args...]
  --check              pipeline + quality gates, emit no C
  --out F              write generated C/asm/QASM to F
  --run                compile with the bundled TCC (or tcc/gcc/clang on
                       PATH) and execute; trailing args are forwarded to
                       the child program
  --target T           baremetal-x86 | baremetal-arm64 | baremetal-avr |
                       baremetal-esp32 | baremetal-quantum | c99 (default)
  -g                   compile inline G source

g, gufran, cpm, apm, and g-lsp are separate binaries built from the same repository.

---

Diagnostics (G-###)

G-010 undeclared/return misuse · G-011 use-after-move · G-012 out-of-scope · G-020 type mismatch · G-021 unification failure · G-030 capability violation · G-040 profile constraint · G-041 backend/board · G-050 default policy · G-060 redefinition · G-070 unrecognized concept · G-071 implicit closure · G-080 unused · G-090 dead code eliminated · G-100 constant folded.

License

MIT — Copyright (c) 2026 SK GUFRAN AHMED. See LICENSE.