jordanhubbard/nanolang: A tiny experimental language designed to be targeted by coding LLMs

A minimal, LLM-friendly programming language with mandatory testing and clear syntax.

NanoLang transpiles into C for native performance while providing a clean, modern syntax optimized for both human readability and AI code generation.

Self-Hosting: NanoLang Stage 0 → Stage 1 → Stage 2 supports true self-hosting via Bootstrap (make bootstrap); See scheme/SELF_HOSTING.md.

git clone https://github.com/jordanhubbard/nanolang.git
cd nanolang
make build

This compiler creates:

• bin/nanoc – Nanolang compiler (transpiles into C)

create hello.nano: :

fn greet(name: string) -> string {
    return (+ "Hello, " name)
}

shadow greet {
    assert (str_equals (greet "World") "Hello, World")
}

fn main() -> int {
    (println (greet "World"))
    return 0
}

shadow main {
    assert true
}

run it:

# Compile to native binary
./bin/nanoc hello.nano -o hello
./hello

NanoLang is actively tested and supported:

• Ubuntu 22.04+ (x86_64)
• ubuntu 24.04 (ARM64) – Raspberry Pi, AWS Graviton, etc.
• macOS 14+ (ARM64/Apple Silicon)
• FreeBSD

Windows 10/11 Users: NanoLang runs perfectly on Windows via WSL2 (Windows Subsystem for Linux).

# In PowerShell (as Administrator)
wsl --install -d Ubuntu

After installation, restart your computer, then:

# Inside WSL Ubuntu terminal
git clone https://github.com/jordanhubbard/nanolang.git
cd nanolang
make
./bin/nanoc examples/language/nl_hello.nano -o hello
./hello

Why WSL? NanoLang’s dependencies (SDL2, ncurses, pkg-config) are Unix/POSIX libraries. WSL2 provides a full Linux environment with almost native performance on Windows.

Comment: Native Windows binaries (.exe) are not currently supported, but may be added in future releases via cross-compilation.

These platforms should work but are not actively tested in CI:

• macOS Intel (via Rosetta 2 on Apple silicon, or native on older Macs)
• Other Linux distributions (Arch, Fedora, Debian, etc.)
• OpenBSD (requires manual dependency installation)

• prefix notation – No operator priority: (+ a (* b c)) is always clear
• mandatory testing – Every function requires one shadow test block
• static typing – Catch errors at compile time
• common types – general union like Result for error handling
• compiled language – Transpiles from C for native performance
• immutable by default – Use let mut for variability
• c interop – Easy FFI via module with automatic package management
• module system – through automatic dependency installation module.json
• standard library – growing stdlib with ResultString ops, math, and more

0. User Guide (HTML) – Progressive tutorial + executable snippet
1. launch – 15 minute tutorial
2. quick reference – syntax cheat sheet
3. language specification – full reference
4. Example – Working examples (all runnable)

# Variables (immutable by default)
let x: int = 42
let mut counter: int = 0

# Functions with mandatory tests
fn add(a: int, b: int) -> int {
    return (+ a b)
}

shadow add {
    assert (== (add 2 3) 5)
    assert (== (add -1 1) 0)
}

# Control flow
if (> x 0) {
    (println "positive")
} else {
    (println "negative or zero")
}

# Loops
let mut i: int = 0
while (< i 10) {
    print i
    set i (+ i 1)
}

No operator precedence to remember:

# Crystal clear - no ambiguity
(+ a (* b c))           # a + (b * c)
(and (> x 0) (< x 10))  # x > 0 && x < 10
(/ (+ a b) (- c d))     # (a + b) / (c - d)

# Primitives
int, float, bool, string, void

# Composite types
struct Point { x: int, y: int }
enum Status { Pending = 0, Active = 1, Complete = 2 }

# Generic lists
let numbers: List = (List_int_new)
(List_int_push numbers 42)

# First-class functions
fn double(x: int) -> int { return (* x 2) }
let f: fn(int) -> int = double

# Generic unions (NEW!)
union Result {
    Ok { value: T },
    Err { error: E }
}

let success: Result = Result.Ok { value: 42 }
let failure: Result = Result.Err { error: "oops" }

NanoLang includes a growing standard library:

union Result {
    Ok { value: T },
    Err { error: E }
}

fn divide(a: int, b: int) -> Result {
    if (== b 0) {
        return Result.Err { error: "Division by zero" }
    }
    return Result.Ok { value: (/ a b) }
}

fn main() -> int {
    let result: Result = (divide 10 2)

    /* Note: Result helper functions (is_ok/unwrap/etc) are planned once
     * generic functions are supported. For now, use match.
     */
    match result {
        Ok(v) => (println v.value),
        Err(e) => (println e.error)
    }

    return 0
}

Look examples/README.md For complete list.

NanoLang includes several modules automated dependency management: :

• curse – Terminal UI (interactive games, text interface)
• sdl – 2D graphics, windows, input (brew install sdl2)
• sdl_mixer – audio playback (brew install sdl2_mixer)
• sdl_ttf – font rendering (brew install sdl2_ttf)
• glfw – OpenGL window management (brew install glfw)

Modules automatically install dependencies via package managers (Homebrew, Apt, etc.) when used for the first time. Look Documents/MODULE_SYSTEM.md For information.

# Build (3-stage component bootstrap)
make build

# Run full test suite
make test

# Quick test (language tests only)
make test-quick

# Build all examples
make examples

# Launch the examples browser
make examples-launcher

# Validate user guide snippets (extract → compile → run)
make userguide-check

# Build static HTML for the user guide
make userguide-html
# Options:
#   CMD_TIMEOUT=600              # per-command timeout (seconds)
#   USERGUIDE_TIMEOUT=600        # build timeout (seconds)
#   USERGUIDE_BUILD_API_DOCS=1   # regenerate API reference
#   NANO_USERGUIDE_HIGHLIGHT=0   # disable highlighting (CI default)

# Serve the user guide locally (dev)
make -C userguide serve

# Clean build
make clean

# Install to /usr/local/bin (override with PREFIX=...)
sudo make install

On BSD systems (FreeBSD/OpenBSD/NetBSD), use GNU: gmake build, gmake testetc.

NanoLang is designed to be LLM-friendly with clear syntax and mandatory testing. To learn how to code an AI system in NanoLang:

• memory.md – Complete LLM training reference with patterns, idioms, debugging workflows and common errors
• spec.json – formal language specifications (types, stdlib, syntax, operations)
• Example – Runable examples demonstrating all features

1. Reading MEMORY.md First – covers syntax, patterns, testing, debugging
2. Reference spec.json for stdlib functions and type descriptions
3. Study examples for idiomatic usage patterns

The combination of MEMORY.md (practical guidance) + spec.json (formal reference) provides full coverage for code creation and understanding.

We welcome contributions! Areas where you can help:

• Add examples and tutorials
• improve documentation
• Report bugs or suggest features
• create new module
• Implement standard library functions

Look contribution.md For guidelines.

current: Production-ready compiler with full self-hosting support.

• ✅ Full language implementation (lexer, parser, typechecker, transpiler)
• ✅ Compiled language (transpiles to C for native performance)
• ✅ Stable typing with prediction
• ✅ Structures, Enums, Unions, Generics
• ✅ Module system with auto-dependency management
• ✅ 49+ standard library functions
• ✅ 90+ working examples
• ✅Shadow-testing framework
• ✅ FFI support for C libraries
• ✅ Memory protection features

Look documents/ROADMAP.md For future plans.

NanoLang solves three problems:

1. llm code generation – Clear syntax reduces AI errors
2. testing discipline – Mandatory testing improves code quality
3. simple and fast – Minimal syntax, basic performance

Design Philosophy:

• Minimal syntax (18 keywords vs 32 keywords in C)
• a clear way of doing things
• Tests are part of the language, not an afterthought
• Transpile to C for maximum compatibility

Apache License 2.0 – see license file for details.