Skip to content

axon-lang

AXON

Section titled “AXON”

AI-Native eXecution Optimized Notation

A programming language designed for AI models to write hyper-efficient native applications. Humans can’t easily read or write it — that’s the point.

What is AXON?

Section titled “What is AXON?”

AXON is a compiler-first, AI-native programming language. It is not designed for human programmers. It is designed to be the output target when an AI model generates high-performance native code.

Traditional programming languages optimize for human readability — meaningful variable names, familiar syntax sugar, implicit conversions, flexible formatting. AXON strips all of that away. What remains is a minimal, unambiguous, fully-explicit notation that a language model can emit deterministically, and a compiler can transform into optimal machine code with zero guesswork.

The current source format is S-expressions (.axs files) — a fully parenthesized prefix notation that eliminates parsing ambiguity. Phase 2 introduces a binary AST format (.axb files) that removes lexing and parsing entirely: the AI emits a token stream of opcodes, type indices, and De Bruijn variable references that the compiler can consume in a single linear pass.

Key Features

Section titled “Key Features”
FeatureDescription
Dual Source FormatS-expression text (.axs, Phase 1) + Binary AST (.axb, Phase 2)
Module System(import) / (use) with visibility enforcement (pub) and qualified access
Linear Type SystemNo garbage collector — compile-time memory management (Phase 2)
Dual BackendQBE IL for fast dev builds, LLVM IR for optimized release builds
De Bruijn ScopingVariable binding uses structural indices, not names (Phase 2)
Region-Based MemoryArena allocation — bulk alloc, bulk free, zero fragmentation
Zero Runtime OverheadNo GC, no dynamic dispatch, no bounds checking
Cross-PlatformmacOS (ARM64) and Linux (x86_64 / ARM64)
Explicit EverythingEvery literal is typed, every conversion is explicit, no implicit coercions

Quick Start

Section titled “Quick Start”

Prerequisites

Section titled “Prerequisites”
  • A C11 compiler (cc, gcc, or clang)
  • QBE (for QBE backend) or LLVM (for LLVM backend)
  • make
  • macOS (ARM64) or Linux (x86_64 / ARM64)

Build the Compiler

Section titled “Build the Compiler”
Terminal window
# Clone the repository
git clone https://github.com/axon-lang/axon.git
cd axon


# Build (debug mode)
make


# Build (optimized)
make release

This produces:

  • build/axonc — the AXON compiler
  • build/libaxon_rt.a — the runtime library

Compile and Run an AXON Program

Section titled “Compile and Run an AXON Program”
Terminal window
# Compile to native binary (QBE backend, default)
./build/axonc examples/fibonacci.axs -o fib
./fib
# Output: 9227465


# Compile with LLVM backend (optimized)
./build/axonc examples/fibonacci.axs -o fib --backend llvm -O2


# Emit QBE IL (for inspection)
./build/axonc examples/fibonacci.axs --emit qbe


# Emit LLVM IR (for inspection)
./build/axonc examples/fibonacci.axs --emit llvm


# Type-check only (no code generation)
./build/axonc examples/fibonacci.axs --check


# Compile and execute in one step — caches the binary for fast re-runs
./build/axonc run examples/fibonacci.axs
# Output: 9227465


# Same again — instant (cache hit)
./build/axonc run examples/fibonacci.axs


# Optimised run
./build/axonc run --release examples/fibonacci.axs


# Watch the import graph and rebuild on every save (Ctrl+C to stop; Linux only)
./build/axonc build --watch examples/fibonacci.axs
# [watch] watching 1 file (debounce 100ms) — press Ctrl+C to stop
# [rebuild] fibonacci.axs → examples/fibonacci (took 210ms)
# ...edit + save the file, and it rebuilds automatically...
# [rebuild] fibonacci.axs → examples/fibonacci (took 118ms)
# Rebuild-and-rerun loop, or a slower debounce, or JSON lines for tooling:
./build/axonc run --watch examples/fibonacci.axs
./build/axonc build --watch --watch-debounce=500 examples/fibonacci.axs
./build/axonc build --watch --json examples/fibonacci.axs


# Emit machine-readable module metadata (functions, types, constants) as JSON
./build/axonc introspect examples/fibonacci.axs --format=json


# Validate the whole standard library as a cheap CI gate (parse + type-check
# every std/*.axs and verify each has a matching *.meta.json). The stdlib root
# is the -L directory or $AXON_STDLIB. Exits non-zero on any failure.
./build/axonc --check-stdlib -L ../axon-std/std
# Also cross-check that a program's std/* imports resolve to real modules:
./build/axonc --check-stdlib -L ../axon-std/std myprog.axs --diagnostics-json

See docs/cli/run.md for the full axonc run reference, docs/cli/introspect.md for axonc introspect, and docs/cli/format.md for axonc format (style presets, --check, --in-place, --diff).

Run Tests

Section titled “Run Tests”
Terminal window
make test

Shell Completions

Section titled “Shell Completions”

Generate tab-completion scripts for your shell:

Terminal window
# Bash — add to ~/.bashrc
eval "$(axonc completions bash)"


# Zsh — add to ~/.zshrc
eval "$(axonc completions zsh)"


# Fish — add to ~/.config/fish/config.fish
axonc completions fish | source


# PowerShell — add to your $PROFILE
axonc completions powershell | Out-String | Invoke-Expression


# Nushell — save to a file and source it
axonc completions nushell | save -f ~/.cache/axonc-completions.nu
source ~/.cache/axonc-completions.nu

Example: Fibonacci

Section titled “Example: Fibonacci”
;; Compute fib(35) = 9227465
(module
  (fn fib ((n i64)) i64
    (if (lt n (i64 2))
      n
      (add (call fib (sub n (i64 1)))
           (call fib (sub n (i64 2))))))


  (fn main () i32
    (block
      (call print_i64 (call fib (i64 35)))
      (i32 0))))

Every integer literal has an explicit type annotation ((i64 2), (i32 0)). Every function specifies parameter types and a return type. There are no implicit conversions.

Example: Multi-File Imports

Section titled “Example: Multi-File Imports”
;; math.axs — a library module
(module
  (pub (fn square ((x i64)) i64
    (mul x x))))
;; main.axs — imports and uses the library
(module
  (import math "math.axs")


  (fn main () i32
    (block
      (call print_i64 (call math.square (i64 7)))  ;; prints 49
      (i32 0))))

Modules use (pub ...) to export functions and (import alias "path") for namespaced access, or (use "path" (fn1 fn2)) to import specific functions directly into scope.

Project Structure

Section titled “Project Structure”
axon/
├── Makefile                 # Build system
├── README.md                # This file
├── docs/
│   ├── language-spec.md     # Complete language specification
│   ├── ai-guide.md          # AI agent programming guide
│   ├── binary-format.md     # Binary AST format specification
│   └── examples/            # Example AXON programs
│       ├── hello.axs
│       ├── fibonacci.axs
│       └── calculator.axs
├── src/
│   ├── axon.h               # Master header (all types & interfaces)
│   ├── main.c               # Compiler driver & CLI
│   ├── arena.c              # Arena allocator
│   ├── diagnostics.c        # Error reporting
│   ├── lexer.c              # S-expression lexer
│   ├── parser.c             # S-expression parser → AST
│   ├── ast.c                # AST construction & printing
│   ├── types.c              # Type system & type table
│   ├── ir.c                 # IR construction & lowering
│   ├── emit_qbe.c           # QBE IL code generation
│   └── emit_llvm.c          # LLVM IR code generation
├── runtime/
│   └── rt.c                 # Runtime library (print_i64, etc.)
├── stdlib/                  # Standard library (future)
└── tests/
    └── programs/            # Test programs (.axs files)

Compiler Pipeline

Section titled “Compiler Pipeline”
.axs text ──► Lexer ──► Parser ──► AST ──► TypeChecker ──► Typed AST
  ──► IR Lowering ──► AXON IR ──► (Optimizer) ──► QBE IL / LLVM IR
  ──► native binary
  1. Lexer — Tokenizes S-expression source into a flat token stream
  2. Parser — Builds an AST from the token stream
  3. Type Checker — Resolves types, enforces type rules, fills in type annotations
  4. IR Lowering — Transforms the typed AST into SSA-form IR (alloca/load/store)
  5. Optimizer — Runs optimization passes on the IR (optional, -O1/-O2)
  6. Backend — Emits QBE IL or LLVM IR from the optimized IR
  7. Assembler/Linker — QBE or LLVM toolchain produces the native binary

Phase Roadmap

Section titled “Phase Roadmap”

Phase 1 — Foundation ✅ COMPLETE

Section titled “Phase 1 — Foundation ✅ COMPLETE”
  • Arena allocator
  • String interning
  • S-expression lexer
  • S-expression parser
  • AST representation
  • Type system (primitives, pointers, arrays, structs, functions)
  • Type checker
  • SSA IR (alloca/load/store style)
  • IR lowering (AST → IR)
  • QBE backend
  • LLVM backend
  • Runtime library (print_i64, print_f64, print_str, print_bool)
  • End-to-end compilation to native binary
  • Test suite (52 E2E tests, 6 error tests)
  • Struct literals (new)
  • Array literals (arr.new)
  • Const declarations (const)
  • Short-circuit evaluation (land, lor)
  • Pointer operations (addr, deref)
  • Module imports (import, use, pub visibility)

Phase 2 — Binary AST & Linear Types (current)

Section titled “Phase 2 — Binary AST & Linear Types (current)”
  • Binary AST format (.axb) — AI emits opcodes directly
  • De Bruijn indices for variables (no name resolution needed)
  • Linearity annotations (@once, @maybe, @many)
  • Memory region annotations (@region, @arena, @pool, @stack)
  • Layout annotations (@soa, @align, @hot/@cold)
  • Constant folding & dead code elimination
  • Inlining pass

Phase 3 — Concurrency & Error Handling

Section titled “Phase 3 — Concurrency & Error Handling”
  • Structured concurrency (spawn, join, select)
  • Actor-based message passing
  • Result types for error handling (ok/err)
  • Pattern matching on result types

Phase 4 — Standard Library & Ecosystem

Section titled “Phase 4 — Standard Library & Ecosystem”
  • Core data structures (vec, map, set)
  • I/O library (files, sockets, stdio)
  • String library (UTF-8, formatting)
  • Math library
  • Memory profiling tools
  • Language server (for AI agent integration)

Phase 5 — Cross-Platform GUI

Section titled “Phase 5 — Cross-Platform GUI”
  • Platform Abstraction Layer (libaxon_pal — window, events, input)
  • macOS backend (AppKit via Objective-C runtime)
  • Linux backend (X11/Wayland)
  • Windows backend (Win32)
  • Software 2D renderer (shapes, text, images)
  • GPU backends (Metal for macOS, Vulkan for Linux/Windows)
  • Flexbox layout engine
  • Immediate-mode UI framework (axon.ui module)
  • Standard widget library (17+ widgets)
  • Dark/Light/Custom theming
  • App bundling (.app, .desktop, .exe)
  • Hot-reload development mode

Benchmarking

Section titled “Benchmarking”

The project includes a benchmark suite for measuring compiler and runtime performance. See benchmarks/README.md for full details.

Terminal window
# Run all benchmarks (results as JSON to stdout)
python3 scripts/run_benchmarks.py


# Run with 5 samples and save results
python3 scripts/run_benchmarks.py --samples 5 --output benchmarks/baseline.json


# Compare against a baseline (exits 1 on regression)
python3 scripts/run_benchmarks.py --baseline benchmarks/baseline.json

Benchmarks include: recursive/iterative Fibonacci, Sieve of Eratosthenes, allocation stress, binary trees, bubble sort, arithmetic loops, and nested loops.

Documentation

Section titled “Documentation”
DocumentDescription
Language SpecificationComplete grammar, type system, and semantics
AI Programming GuideHow to write AXON programs (for AI models)
Binary Format SpecPhase 2 binary AST wire format
GUI ArchitectureCross-platform GUI framework design

License

Section titled “License”

MIT License. See LICENSE for details.

Copyright (c) 2026 AXON Project.