Quick Start

Build the compiler, write your first program, and start compiling in minutes.

📋 Prerequisites

A C11 compiler (cc, gcc, or clang)
QBE (for QBE backend) or LLVM 15+ (for LLVM backend)
make
macOS (ARM64) or Linux (x86_64 / ARM64)

🔨 Build the Compiler

bash

# Clone the repository
git clone https://git.catalystgroup.tech/labs/axon/axon-lang.git
cd axon-lang

# Build (debug mode)
make

# Build (optimized)
make release

This produces build/axonc (the compiler) and build/libaxon_rt.a (the runtime library).

👋 Hello World

hello.axs

(module
  (extern print_str ((s (ptr i8))) void)

  (fn main () i32
    (block
      (call print_str (str "Hello, World!"))
      (i32 0))))

▶️ Compile & Run

bash

# Compile to native binary (QBE backend, default)
./build/axonc hello.axs -o hello
./hello
# Output: Hello, World!

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

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

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

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

⌨️ CLI Reference

Option	Description
`-o FILE`	Output file path
`--backend qbe\|llvm`	Select backend (default: `qbe`)
`-O0`, `-O1`, `-O2`	Optimization level (default: `0`)
`--check`	Type-check only, don't compile
`--emit qbe\|llvm\|ast\|ir`	Emit intermediate representation
`--target TRIPLE`	Set target triple (default: auto-detect)
`--verbose`	Print compilation stages

🔧 Build System

Command	Description
`make`	Debug build
`make release`	Optimized build
`make clean`	Remove build artifacts
`make test`	Run test suite
`make install`	Install to /usr/local/bin

📚 Runtime Library

The AXON runtime (libaxon_rt.a) provides these built-in functions. Declare them with extern:

Function	Signature	Description
`print_i64`	`(i64) → void`	Print 64-bit integer + newline
`print_f64`	`(f64) → void`	Print 64-bit float + newline
`print_str`	`((ptr i8)) → void`	Print null-terminated string + newline
`print_bool`	`(bool) → void`	Print `true` or `false` + newline

🏷️ Enums Quick Start

enum_example.axs

(module
  (extern print_i64 ((n i64)) void)
  (enum Direction i32 ((North 0) (South 1) (East 2) (West 3)))

  (fn main () i32
    (block
      (call print_i64 (cast i64 (Direction North)))
      (i32 0))))

🔀 Pattern Matching Quick Start

match_example.axs

(module
  (extern print_i64 ((n i64)) void)

  (fn classify ((x i32)) i64
    (match x
      ((i32 0) (i64 100))
      ((i32 1) (i64 200))
      (_       (i64 999))))

  (fn main () i32
    (block
      (call print_i64 (call classify (i32 0)))
      (call print_i64 (call classify (i32 42)))
      (i32 0))))

Output: 100 999

🧬 Sum Types Quick Start

sum_types.axs

(module
  (extern print_i64 ((n i64)) void)
  ;; Declare a sum type with two variants
  (sum Option ((None) (Some i64)))

  (fn unwrap_or ((opt Option) (default i64)) i64
    (match opt
      ;; bind payload to 'val'
      ((Option.Some val) val)
      ((Option.None) default)))

  (fn main () i32
    (block
      ;; Construct with Type.Variant
      (call print_i64 (call unwrap_or (Option.Some (i64 42)) (i64 0)))
      (call print_i64 (call unwrap_or (Option.None) (i64 -1)))
      (i32 0))))

Output: 42 -1