Skip to content

Repository files navigation

Freak-docs

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.


What's here

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.

Repository layout

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.

Local preview

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      # Linux

Or serve it:

python -m http.server 8000 --directory site

Deploying

Vercel, 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.

Regenerating

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 -v

The 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.

The V4 notes

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-lang

verify_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.

Directives

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.

Embedding in freaklang.dev

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-v3

That 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.

No emoji

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.

Two compiler defects documented here

Found while writing these docs, reproduced against the current main, and documented rather than worked around silently:

  • array_sort_word() segfaults. It routes through extern task freak_word_compare(a: word, b: word) -> int, and that declaration does not bridge the LLVM backend's word handle representation.
  • array_unique() returns an empty array.

Caveat: V3 moves inside its version number

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.

Contributing

  1. Edit content/*.md, or add an example under examples/, diagnostics/v3/ or examples-v4/.
  2. Add or review the expectation beside it. Never paste in whatever the program printed without reading it.
  3. Run tools/refresh.py — verification, generation and search checks must pass.
  4. 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.

Licence

Documentation and examples follow the licence of the FREAK language repository.

Releases

Packages

Contributors

Languages