Documentation for the FREAK V3 "Maverick" compiler — the shipping,
self-hosted generation in
src/compiler/v3/.
Written against what the compiler actually accepts, not what the
specification promises. Badged executable examples are real files in
examples/, compiled by a released V3 binary, executed, and checked
against reviewed expected output. Inline illustrative fragments are labelled
separately and do not carry a verification claim.
See examples/verified.json for the current compiler release, exact provenance,
and per-example results. MAINTENANCE.md defines the V3 release
policy and the separate development-snapshot policy for V4 notes.
The repository also holds The Freak Book, a tutorial read in order
(content/book*.md). It teaches V3, shows the diagnostics V3 really prints,
and carries clearly marked notes about V4 that are checked against one pinned
V4 commit. BOOK_PLAN.md is its outline and status.
| The Freak Book, Part I | Introduction and five chapters: installing, a guessing game, pilots and types, tasks, control flow |
| 4 getting-started pages | Overview, building the compiler, the CLI, Hangar & packages |
| 3 tutorials | First program · A command-line tool · Modelling data |
| 10 language pages | Bindings, tasks, control flow, operators, words, shapes, lists, colour, anime layer, FFI |
| 5 reference pages | Standard library, grammar, bible-vs-V3 conformance, what's missing, the example gallery |
| Full-text search | Client-side, no server, / or Ctrl/Cmd+K |
The two pages worth reading even if you know FREAK:
- Bible vs V3 — a feature-by-feature comparison
against
freak-full-bible.md, with the actual compiler diagnostics. Roughly a fifth of the specification compiles today. - Not in V3 — a working substitute for each missing feature.
- Hangar & packages — Hangar installs dependencies the compiler cannot link. What to do instead.
content/ documentation source (a small Markdown subset)
examples/ .fk programs; every code block on the site comes from here
expectations.json reviewed output per program; optional `stdin`, `args`, `exit_code`
verified.json compile/run results, regenerated by tools/verify.py
diagnostics/v3/ programs V3 must REJECT, each with the reviewed text of its diagnostic
examples-v4/ programs for the V4 notes: must run, or must be rejected, at the pinned commit
verified.json V4 results (generation v4, channel development), from tools/verify_v4.py
v3-release.txt the stable V3 release every V3 claim is checked against
v4-snapshot.txt the one Freak-lang commit every V4 note is checked against
meta/
labels.json org-wide GitHub label taxonomy (source of truth)
LABELS.md the taxonomy, its rationale, and how to apply it
tools/
verify.py builds and runs every example with a real V3 compiler, and
confirms every rejected program is refused for the reviewed reason
verify_v4.py checks examples-v4/ against a Freak-lang checkout at the pinned commit
build_docs.py renders content/ + verified.json into site/
ansi_html.py replays captured terminal output (SGR, CR, cursor) as HTML
status_pills.py inline SVG conformance markers, so no page needs emoji
search_smoke.js headless check that the search index answers real queries
sync_labels.py applies meta/labels.json to the org's repos
site/ the generated website — this is what Vercel serves
vercel.json static deployment config
site/ is committed deliberately: the build needs a working FREAK compiler,
which Vercel has no way to produce, so the generated HTML is the deployment
artefact.
No server needed — the site is self-contained, with no CDN and no fetch:
open site/index.html # macOS
start site\index.html # Windows
xdg-open site/index.html # LinuxOr serve it:
python -m http.server 8000 --directory siteVercel, as a static project with no build step:
| Setting | Value |
|---|---|
| Framework preset | Other |
| Build command | (leave empty) |
| Output directory | site |
| Install command | (leave empty) |
vercel.json already sets outputDirectory, so importing the repo should need
no manual configuration.
Use the official stable V3 release distribution, including its matching runtime and standard library. Requires Python 3.12+, Node.js, GitHub CLI and Clang.
python tools/refresh.py --jobs 6
python -m unittest discover -s tests -vThe default compiler is pinned in v3-release.txt. To adopt a newer stable V3
release, update that file and commit the regenerated report and site together.
--release vX.Y.Z remains available for manual evaluation. PR CI rejects stale
committed output before running the compiler again.
verify.py copies each example into a clean temporary directory, runs
freak build with the default LLVM backend, executes the binary, checks its
output against examples/expectations.json, and writes examples/verified.json.
Compilation failures, runtime failures, missing executables, timeouts and wrong
output all fail the run. build_docs.py independently rejects stale, partial or
failing evidence before writing any output. --only is for debugging and must
write to a separate --output file.
V4 has no release, so its notes are checked against a source checkout:
git clone https://github.com/FREAK-lang-dev/Freak-lang ../Freak-lang
git -C ../Freak-lang checkout "$(cat v4-snapshot.txt)"
python tools/verify_v4.py --checkout ../Freak-langverify_v4.py refuses a checkout at any other commit or with local compiler
changes. It builds each program with that commit's own
src/compiler/v4/build_v4.py, runs the ones that must run, and requires the
reviewed diagnostic from the ones that must be rejected. build_docs.py
refuses to render a {{v4:name}} card without matching evidence. To move the
notes to a newer V4, change v4-snapshot.txt, re-run, and correct every note
the new commit contradicts. Expect some: that is the point of pinning.
| In a page | Renders |
|---|---|
{{example:name}} |
A verified V3 program with its output, input and exit code |
{{example:name|source}} |
The same program, source only |
{{diagnostic:name}} |
A program V3 rejects, with the diagnostic it printed |
{{v4:name}} |
A program checked against the pinned V4 commit: output, or V4's diagnostic |
{{v4-snapshot}} |
A summary card naming the pinned V4 commit |
> [!maverick] |
An "In V4" box |
> [!planned] |
A "Planned" box, for specification-only features |
build_docs.py renders the site and rebuilds the search index. Coloured
program output is preserved by the harness and re-rendered as HTML: the
generator implements a stateful SGR renderer (attributes, 16 colours,
backgrounds, 256-colour, truecolour, selective resets) and drops non-SGR
control sequences.
Adding a page means adding content/<slug>.md and an entry in the NAV table
at the top of build_docs.py.
The same build also emits an embeddable form, used by the /docs/v3 section of
freaklang.dev:
python tools/build_docs.py --fragments /path/to/freaklang.dev/apps/main-site/public/docs-v3That writes body-only HTML fragments (no <head>, no chrome, in-page links
rewritten to ./slug#anchor), plus manifest.json describing the sidebar
groups, page order and per-page <h2> anchors, and search-index.json. The
host site supplies its own styling and navigation and drives everything from
the manifest, so a page added here appears there without any code change.
Regeneration is documented on that side in scripts/sync-v3-docs.md.
Conformance markers are inline SVG pills (:shipped:, :partial:, :v4:,
:planned: in the Markdown source), not emoji. Emoji render inconsistently
across platforms, carry no accessible name, and cannot inherit the surrounding
colour; an SVG stroked with currentColor does all three. The favicon is an
SVG mark for the same reason.
Found while writing these docs, reproduced against the current main, and
documented rather than worked around silently:
array_sort_word()segfaults. It routes throughextern task freak_word_compare(a: word, b: word) -> int, and that declaration does not bridge the LLVM backend'swordhandle representation.array_unique()returns an empty array.
The compiler generation is frozen for new semantics, but the builtin table is
not, and it moves fast. Within 0.14.1 V3 gained a typed List<T>, a builtin
ByteBuffer, the word_builder::* accumulator, a tcp::socket_* family that
can listen and accept, word.repeated(n), time::monotonic_ns(),
process::pid(), process::set_env() and ui::set_clip. 0.14.2 then made
lists growable (push/pop/reserve/capacity/clear, List::new,
List::with_capacity), added checked parse_int/parse_num with a global
parse_status(), and allowed += on words. An older compiler can no longer
compile the current std/.
For maintained V3 release docs, use tools/refresh.py with the matching release
distribution and re-run it after changing documented inputs. Do not substitute a
development build just because it prints the same version number.
- Edit
content/*.md, or add an example underexamples/,diagnostics/v3/orexamples-v4/. - Add or review the expectation beside it. Never paste in whatever the program printed without reading it.
- Run
tools/refresh.py— verification, generation and search checks must pass. - Commit the report and regenerated
site/. CI rechecks every example with the release.
Prose rule: if a page states that something works, there should be a verified example backing it. If something is broken, say so and show the diagnostic.
Documentation and examples follow the licence of the FREAK language repository.