Docs: rewrite the outdated README (native+web backends, stdlib, links) #35

New issue

Closed

opened 2026-08-30 12:50:37 +02:00 by orkun · 1 comment

orkun commented

2026-08-30 12:50:37 +02:00

Owner

Problem

README.md is outdated and no longer matches the repository:

It's macOS-centric ("the macOS window, written in LLVM IR") and predates the
wasm/web backend (runtime/web/), which now exists but isn't reflected in
the pitch.
The Layout table references a curated few files but the repo has grown a
large namespaced standard library (Math, Vector, Time/Date/Duration,
Crypto, Hash, sorting, …) and an issue-driven proposal backlog that the
README doesn't mention at all.
It doesn't point to the docs site, the wiki (once design docs move
there), or the issue tracker / proposals — so a newcomer has no map of
where to go.
After the planned repo reorg (examples/, selfhost/ subdirs), the layout table
will be stale again unless rewritten.

Proposal

Rewrite the README as a real entry point:

Tight one-paragraph pitch (compiled, self-hosted, C-free, ECS, 2D native and
web/wasm).
Quick start that actually works (bootstrap one-liner → bin/x app examples/… → run), verified against current bin/x.
A layout table that matches the post-reorg structure.
Clear links out: docs site, wiki (design/roadmap), examples index, contributing,
proposals/issues.
Status/roadmap section pointing at the tracker instead of inlining a giant
roadmap.

Acceptance criteria

README reflects current backends (native + web) and the stdlib.
Quick-start commands verified end-to-end.
Layout table matches the reorganised tree.
Links to docs, wiki, examples, contributing, issues.

Do this after the wiki move and the examples/selfhost reorg so the map is
accurate. Part of the repository-cleanup / DX pass.

## Problem `README.md` is outdated and no longer matches the repository: - It's macOS-centric ("the macOS window, written in LLVM IR") and predates the **wasm/web backend** (`runtime/web/`), which now exists but isn't reflected in the pitch. - The **Layout** table references a curated few files but the repo has grown a large namespaced **standard library** (Math, Vector, Time/Date/Duration, Crypto, Hash, sorting, …) and an **issue-driven proposal backlog** that the README doesn't mention at all. - It doesn't point to the **docs site**, the **wiki** (once design docs move there), or the **issue tracker / proposals** — so a newcomer has no map of where to go. - After the planned repo reorg (examples/, selfhost/ subdirs), the layout table will be stale again unless rewritten. ## Proposal Rewrite the README as a real entry point: - Tight one-paragraph pitch (compiled, self-hosted, C-free, ECS, 2D native **and** web/wasm). - **Quick start** that actually works (bootstrap one-liner → `bin/x app examples/…` → run), verified against current `bin/x`. - A layout table that matches the **post-reorg** structure. - Clear links out: docs site, wiki (design/roadmap), examples index, contributing, proposals/issues. - Status/roadmap section pointing at the tracker instead of inlining a giant roadmap. ## Acceptance criteria - [ ] README reflects current backends (native + web) and the stdlib. - [ ] Quick-start commands verified end-to-end. - [ ] Layout table matches the reorganised tree. - [ ] Links to docs, wiki, examples, contributing, issues. Do this **after** the wiki move and the examples/selfhost reorg so the map is accurate. Part of the repository-cleanup / DX pass.

orkun added the

priority:medium

area:docs

labels 2026-08-30 12:50:37 +02:00

orkun referenced this issue from a commit

2026-08-30 17:57:48 +02:00

docs: rewrite README as an accurate entry point (#35)

orkun closed this issue

2026-08-30 18:10:35 +02:00

orkun commented

2026-08-30 18:10:48 +02:00

Author

Owner

Done in a422ef4 (follows the examples reorg in #28, which the layout table now reflects).

Acceptance criteria

README reflects current backends (native + web) and the stdlib — replaced the macOS-centric framing with a Backends table: native 2D is the shipping default; the web/wasm platform layer (runtime/web/) and the native-vs-wasm diff harness (tools/ludic-web/run.mjs) are in-tree and documented, but emitting wasm is not yet re-wired on the self-hosted toolchain (it was a retired-C-compiler capability, per COMPILING.md). Added a "Language at a glance" section that names the namespaced stdlib (Math, Vector, Time/Date/Duration/Clock, Random, Hash, Crypto, sorting, …).
Quick-start commands verified end-to-end — the clang seed one-liner, bin/x build, bin/x app examples/games/snake.ludic, and the headless flow (now writing build/out.ppm) were all run and confirmed while writing the section.
Layout table matches the reorganised tree — points at the examples/ subdirectories and examples/README.md, the golden hash manifest, runtime/native + runtime/web, the tooling and docs.
Links to docs, wiki, examples, contributing, issues — a Status & roadmap section links out to the issue tracker/proposals, the docs site, and the wiki, and links to examples/README.md and CONTRIBUTING.md, instead of inlining a giant roadmap.

Correction worth flagging: the old README claimed --target wasm32 and ELF/COFF cross-compilation as implemented while its own prose said they'd retired with the C compiler. The rewrite makes the honest statement — native ships today; web/wasm, --target, and --shared are designed and documented but pending re-implementation on the self-hosted toolchain.

Done in a422ef4 (follows the examples reorg in #28, which the layout table now reflects). **Acceptance criteria** - [x] **README reflects current backends (native + web) and the stdlib** — replaced the macOS-centric framing with a **Backends** table: native 2D is the shipping default; the web/wasm platform layer (`runtime/web/`) and the native-vs-wasm diff harness (`tools/ludic-web/run.mjs`) are in-tree and documented, but emitting wasm is **not yet re-wired on the self-hosted toolchain** (it was a retired-C-compiler capability, per COMPILING.md). Added a "Language at a glance" section that names the namespaced stdlib (Math, Vector, Time/Date/Duration/Clock, Random, Hash, Crypto, sorting, …). - [x] **Quick-start commands verified end-to-end** — the clang seed one-liner, `bin/x build`, `bin/x app examples/games/snake.ludic`, and the headless flow (now writing `build/out.ppm`) were all run and confirmed while writing the section. - [x] **Layout table matches the reorganised tree** — points at the `examples/` subdirectories and `examples/README.md`, the golden hash manifest, `runtime/native` + `runtime/web`, the tooling and docs. - [x] **Links to docs, wiki, examples, contributing, issues** — a Status & roadmap section links out to the issue tracker/proposals, the docs site, and the wiki, and links to `examples/README.md` and `CONTRIBUTING.md`, instead of inlining a giant roadmap. **Correction worth flagging:** the old README claimed `--target wasm32` and ELF/COFF cross-compilation as *implemented* while its own prose said they'd retired with the C compiler. The rewrite makes the honest statement — native ships today; web/wasm, `--target`, and `--shared` are designed and documented but pending re-implementation on the self-hosted toolchain.