Flash

A small systems language that compiles to Zig — now compiling itself, and, in time, FlashOS

README · Vision · Tutorial · Reference · Cookbook · Setup · Versioning · Changelog · License

About

Flash is a statically typed, freestanding-capable systems language. Its compiler, flashc, is written in Flash itself — self-hosted as of v0.5.0 — and, in its first incarnation, lowers Flash source to Zig source rather than to machine code. The Zig toolchain then performs code generation, linking, and alignment-sensitive lowering. A frozen, handwritten-Zig seed compiler stays in-tree so a clean clone bootstraps with nothing but a Zig toolchain: the seed builds the compiler from its Flash sources, that compiler rebuilds itself, and the build asserts both generations emit byte-identical code.

This "Tier 0" strategy exists for one reason: Flash is being built to rewrite a real, working operating system — FlashOS, an AArch64 bare-metal kernel — without regressing its boot contract or its test suite at any step. Emitting Zig lets Flash and Zig sources coexist module by module, so the migration is incremental rather than a rewrite.

Flash is an independent side project. FlashOS is its first consumer, not a dependency.

Why

FlashOS is roughly 26,000 lines of Zig today. The aim is not to replace Zig for its own sake, but to own the entire stack — language, compiler, kernel, and shell — end to end, in the same spirit that drove the original C→Zig port. Flash is the language layer of that ambition.

Approach

The frontend (lexer, parser, AST, sema) is reused unchanged if the backend is later swapped; only lowering is replaced. See VISION.md.

Status

Pre-alpha. v0.6.0 is released: the low-level language register an operating system needs is complete, and Flash has the seed of its own standard library. The compiler has been self-hosted since v0.5.0 — the maintained flashc source is Flash (selfhost/), the handwritten Zig compiler under src/ is the frozen bootstrap seed, and zig build fixpoint certifies on every build that the generation chain stays closed. On that footing, the v1 syntax surface (frozen at v0.4.0, growing additively only) gained its booked systems forms: wrapping compound assignment (+%= -%= *%=), array repetition (**), export/extern variables, linksection(…), packed/extern struct layouts, callconv in function types, pointer captures (|*x|), labeled loops, align(N) in pointer types and on bindings, and errdefer |err| capture. And std/ is born: the core module lands memory primitives, the List(T) dynamic array, comptime-checked formatting and integer parsing, integer bounds, and an arena allocator — all pure Flash, with the self-hosted compiler itself running on them. See the changelog for what has landed.

Building

Requires Zig 0.16.0 exactly (pinned; see .zigversion). Full steps in SETUP.md.

zig build                # build flashc (the stage0 bootstrap seed) into zig-out/bin
zig build test           # run the host unit + integration suite (includes test-flash, test-selfhost, test-std, test-lsp, and test-driver)
zig build test-flash     # transpile and run the .flash test suite (tests/flash/)
zig build test-selfhost  # transpile and run the self-hosted compiler's test suite (selfhost/)
zig build test-std       # transpile and run the standard library's test suite (std/)
zig build test-lsp       # transpile and run the language server's test suite (tools/lsp/)
zig build test-driver    # assert the build driver's file outputs, exit codes, and flag composition
zig build stage1         # build flashc-stage1 — the compiler built from the Flash sources
zig build stage2         # build flashc-stage2 — stage1 rebuilding the compiler from the same sources
zig build diff-corpus    # assert flashc and flashc-stage1 behave byte-identically over the corpus
zig build fixpoint       # assert stage1 and stage2 emit byte-identical Zig, deterministically
zig build lsp            # build flashd, the Flash language server (editor wiring in editors/)

# transpile a Flash program to Zig (lowered source on stdout, or -o FILE):
zig-out/bin/flashc examples/hello.flash

# transpile a whole source tree, mirroring relative paths (src/**.flash -> gen/**.zig):
zig-out/bin/flashc build src gen

# reformat a .flash file in place (--check reports without writing):
zig-out/bin/flashc fmt examples/hello.flash

# inspect the token stream, or print the version:
zig-out/bin/flashc --dump-tokens examples/clear.flash
zig-out/bin/flashc --version

Tutorial

An interactive, browser-based tutorial — twelve chapters beside a live code editor — is hosted at ajhahnde.github.io/Flash. Reading and loading examples into the editor are fully static; for live Flash → Zig transpilation run the bundled dev server (cd tutorial && npm install && npm start).

For the full syntax and semantics in one document see the Language Reference; for small, copyable patterns — allocators, error handling, casts, bit work, JSON — see the Cookbook.

Layout

selfhost/    the compiler — flashc written in Flash (support.flash is the std shim)
std/         the Flash standard library — the `core` module, written in Flash
src/         the frozen bootstrap seed — the handwritten Zig compiler (bugfixes only)
tests/       integration tests over the example sources
examples/    sample .flash programs (hello, clear, and /bin coreutil ports;
             register/ holds post-bootstrap grammar samples)
editors/     VS Code + Neovim syntax grammars and the language-server wiring
tutorial/    interactive web tutorial (GitHub Pages + local dev server)
assets/      logo
tools/       host-side build tooling (the diff-corpus and fixpoint harnesses)
             and tools/lsp/ — flashd, the Flash language server, written in Flash
.github/     CI + Pages workflows

AI assistance

The prose docs in this repo (README, CHANGELOG, REFERENCE, COOKBOOK, VISION) and the tutorial are LLM-drafted under my review. They're kept honest by the build, not by trust: every behavioral claim maps to something CI runs.

• zig build test — the compiler test suite (lexer → parser → sema → lower)
• zig build diff-corpus — asserts the Zig seed (stage0) and the self-hosted compiler (stage1) behave identically
• zig build fixpoint — asserts stage1 and stage2 emit byte-identical Zig, i.e. the compiler reproduces itself exactly

All three run on every push. If a doc claims the bootstrap closes, the fixpoint gate is what proves it.

The docs are also kept current automatically: a contract-literal drift check verifies the version, the Zig pin, and the zig build target names quoted in these files against the live tree, so a stale copy is caught rather than shipped.

Source code (src/*.zig, selfhost/*.flash, std/, tools/) is authored by me.

License

Apache-2.0. See LICENSE.md.

See also

• FlashOS — the operating system Flash is written in.
• eeco — self-maintaining workflow ecosystem.
• the-way-out — top-down pixel-art escape-room shooter.
• Theria — 2.5D MOBA built in Godot 4.

Next: Vision →