x-lang Documentation
Getting Started
- Tutorial — Build, run, and write your first x-lang programs
- Pinning, step by step — Set up a pinned project, retrofit an existing one, pin the platform
- Sandboxing and type reflection, step by step — Make an isolated interpreter, hand it capabilities, teach it types, inspect anything
- README — Project overview, build instructions, feature summary
- AGENTS.md — the briefing for coding agents: running it, the
Lisp assumptions that fail here, and how to find what exists
(llms.txt indexes this page)
Language
- Specification — Normative specification of the core language
- Glossary — One name per concept: the settled cross-layer vocabulary
- Syntax — The preferred forms and idioms (least surprise)
- Bare Syntax — The reader spec any implementation must match
- Architecture — System design, evaluation model, the contract pattern
- The Engine Contract — What an engine must provide, promise and report; how a second implementation is checked
- Engine Laws — behaviour the language requires of an engine that the contract’s files cannot state, and the check for each
- Type System — Objects, types, the base object, dispatch, extensibility
- Object System — Message-passing classes, single inheritance, encapsulated fields,
super
- Dialects — the helium, xenon, and radon dialect layers
- The Lang Contract — what a lang may rely on, and how one is acquired as a pinned bundle
- Crafting a Lang — how one is actually built: the reader’s machinery, the type-system mapping, the rules that bite, distilled from building x-python
- Bundle Checklist — recurring defects in lang bundles (memory, state images, CI, specs), each with its check and remedy
- Scaling to Many Langs — what has to be true for there to be twenty of them: five rulings, three built
- Modules —
provide, import and include; a scope per module and the rule for each name conflict; pinning a project’s libraries (pin.xon)
- Reflection — looking inside a running system: the doors onto values, types, classes, callables, environments, modules, source positions, the base and the heap, by level
- State Images — why the state image writer, loader and format are shaped as they are; the format itself is State image format
Reference
- The interactive session — the built-in line editor: keys, history, completion, as-you-type colour, and how to replace the loop
- Primitives and core forms — the engine’s instruction set, the coordinates reached through
prim-ref, and the operatives and procedures that boot on top (hand-written)
- Standard Library — how the library is laid out and how to find a name in it; the reference itself is generated
- x-lang API Reference — complete library reference, auto-generated from the
(doc ...) forms in lib/x/**
- C API Reference — the C engine, generated by Doxygen from that engine’s own sources
Both generated references are published from main by CI and are not committed.
To read them offline, make doc-x writes the library’s to ref/x/, and
make doc-c has the engine write its own under the engine’s docs/ref/c/.
- Dev tools — Formatter, linter, coverage, benchmarks, doc generation
Project