This guide is the tour. The canonical contract — what the
compiler actually enforces — lives in the spec/ directory at
the repository root. When the guide and the spec disagree, the
spec wins; when you need the exact rule, an edge case, or a
diagnostic’s meaning, go there.
| You want |
Read |
| The formal grammar |
spec/grammar.ebnf |
| Lexical structure, literals, operators |
spec/tokens.md |
| Operator precedence & associativity |
spec/precedence.md |
| Operational semantics (lifecycle, bus, recovery, fallible) |
spec/semantics.md |
| The type system |
spec/types.md |
| Memory: regions, capacity slots, projection classes |
spec/memory.md |
The form library (vec / hashmap / ring_buffer) |
spec/forms.md |
| The always-loaded runtime |
spec/runtime.md |
| The standard library surface |
spec/stdlib.md |
| Idiomatic patterns, the seven shapes, correctness + speed rules |
spec/styleguide.md |
The FFI contract — C (@ffi("c")) and the WASM host interface (@ffi("js") / @export) |
spec/ffi.md |
| Dependencies & vendoring |
spec/packages.md |
| Project layout & imports |
spec/projects.md |
| How tests are written and run |
spec/testing.md |
| Why the current surface is shaped this way |
spec/design-rationale.md |
| The design-decision log (the F-series: commitments, rejects, sketches) |
spec/decisions.md |
| Internal codename legend (milestone / workstream tags) |
spec/glossary.md |
AGENTS.md — the load-bearing prompt for
agents writing .hl. It condenses the six idiomatic patterns,
the “what’s not in the language” reflexes, and the formal
design model into one file. Excellent for a human, too.- Working programs —
crates/hale-codegen/tests/fixtures/examples/
holds 83 small per-feature programs, numbered. Reading a few
near your target shape is the fastest way to see real,
compiling Hale.
| Command |
Does |
hale init [dir] |
bootstrap a project: hale.toml, a hello-world seed, a first test, .gitignore — non-destructive, fills in only what’s missing |
hale run <file/dir> |
compile + run (fast feedback) |
hale build <file/dir> |
compile to a native binary |
hale check |
parse + typecheck only |
hale test |
run *_test.hl |
hale fetch |
clone & pin git dependencies |
hale fmt |
canonical formatter |
hale verify |
check, but any advisory fails too (the CI gate) |
hale bench |
run *_bench.hl (ns/op, allocs/op) |
hale doc |
API reference from /// comments |
hale fleet |
compose topology artifacts across binaries: check / dump / sign / attest / keygen |
hale lsp |
the language server, in the compiler binary |
hale mcp |
the MCP server, in the compiler binary |
hale