docs/trust.md lists every badge and verdict the app shows (where code came from, what a compiler said, what a proof, the fuzzer, a translation and the model machine say): what earns each one, what it means, and what it does not mean. New badges get a row there in the same commit. pixi run package zips the files git tracks, plus new files it does not ignore, into package/programming-plus-<commit>.zip (marked -dirty with uncommitted changes). The zip shared before this held .DS_Store files, __pycache__ folders and __MACOSX entries (3,661 files); the package holds none of them (1,694 files). Python standard library only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
121 lines
9.0 KiB
Markdown
121 lines
9.0 KiB
Markdown
# Programming+
|
|
|
|
Programming+ takes a procedure **from an idea to Mojo to the machine**, built for a world where writing code is easy and knowing what it does is the job. It has three areas (`src/core/areas.ts`):
|
|
|
|
- **Bridge**: write the procedure as plain-English steps (**lingo**), equations written in LaTeX (**matho**), the notation that can completely specify any procedure (**pseudo**), or a specification you prove against (**speco**); the others follow as you type, and Mojo is generated from the pseudo, always labeled as generated.
|
|
- **Developer**: Mojo only. The checker's advice as you type, every step and every value in one Run view, a fuzzer that lists what it tried, and the real Mojo compiler's verdict.
|
|
- **Hardware**: the code beside a board you arrange: registers, memory, the stack, cache lines, the caches, virtual memory, the pipeline and the out-of-order core, with Mojo and its x86-64 as tabs, linked line by line.
|
|
|
|
A catalog of worked problems comes with it, each opening in every area it has something to show in, and any view can be shared as a link or embedded in a page. With Quarto, a page can also run a program kept beside it while the page renders, and show the run, a stepper, the flowchart, the proof and the rest without an iframe, down to the machine itself (registers, caches, the pipeline, the core, stepped). The **With Quarto** page (`#/quarto`) is a gallery of every shortcode.
|
|
|
|
It is a static single-page app: TypeScript compiled by `tsc`, no bundler, no framework, no runtime dependencies. Everything it says about Mojo is pinned to **Mojo 1.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org).
|
|
|
|
## Quick start
|
|
|
|
With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
|
|
|
|
```bash
|
|
pixi run dev # build, then serve on http://localhost:4173
|
|
pixi run test # build, then every test
|
|
```
|
|
|
|
Without pixi, with Node 20 or later (and `python3` for the corpus pipeline's tests):
|
|
|
|
```bash
|
|
npm install && npm test
|
|
npm run dev
|
|
```
|
|
|
|
## Commands
|
|
|
|
Every command is a pixi task (`pixi task list` shows them with their descriptions). `tests/tasks.test.mjs` fails if this table and `pixi.toml` disagree.
|
|
|
|
| Task | What it does |
|
|
|---|---|
|
|
| **Build and test the app** | |
|
|
| `install` | Install TypeScript, the only npm dependency |
|
|
| `build` | Compile `src/` to `dist/` |
|
|
| `watch` | Rebuild `dist/` on every change |
|
|
| `check` | Type-check only |
|
|
| `dev` | Build, then serve on http://localhost:4173 |
|
|
| `test` | Build, then run every test, the corpus pipeline's Python tests included |
|
|
| `check-pages <dir>` | Run every program embedded in the Quarto pages under a folder ([quarto/README.md](quarto/README.md)) |
|
|
| `engines-diff <static>` | Show what a course checkout has not taken yet from the engines and stylesheets ([docs/engines.md](docs/engines.md)) |
|
|
| `engines-export <static>` | Copy the engines into a course checkout, TypeScript modules as built ([docs/engines.md](docs/engines.md)) |
|
|
| **Write content** | |
|
|
| `new-exercise <id>` | Start an exercise whose Mojo lives in `mojo/local/<id>.mojo` ([docs/exercises.md](docs/exercises.md)) |
|
|
| `new-probe <name> <question>` | Start `mojo/probes/<name>.mojo`: one question about the compiler ([docs/mojo-corpus.md](docs/mojo-corpus.md)) |
|
|
| `new-stress <name> <about>` | Start `mojo/stress/<name>.mojo`: realistic Mojo that tests the interpreter |
|
|
| `play <name>` | For `mojo/local/<name>.mojo`: run, verify on godbolt, build, list the assembly, test |
|
|
| `play-watch <name>` | The same, again on every save (tests off) |
|
|
| `quarto-export <name> <dir>` | Copy a `mojo/local/` program, its x86-64 and setup beside a Quarto page, and print the shortcode |
|
|
| `quarto-css` | Regenerate the extension's `pplus-views.css` from `styles.css` (a test fails while it is out of date) |
|
|
| `quarto-engine <dir>` | Copy a built Programming+ into a site's `_extensions/pplus/engine`, for the rendered views ([quarto/README.md](quarto/README.md)) |
|
|
| `quarto-example` | Render the example site in `quarto/example`, every shortcode on real pages (needs Quarto) |
|
|
| **The Mojo corpus** ([docs/mojo-corpus.md](docs/mojo-corpus.md)) | |
|
|
| `mojo-verify` | Ask godbolt about every program with no answer yet (network) |
|
|
| `mojo-verify-item <id>` | Ask again about one item, e.g. `'probes/life-*'` (network) |
|
|
| `mojo-verify-dry` | Show what `mojo-verify` would send; send nothing |
|
|
| `mojo-verify-diagnostics` | Also check the compiler's own diagnostic tests (opt-in; network) |
|
|
| `mojo-status` | Judge every item from the stored answers, offline; writes `mojo/golden/STATUS.md` |
|
|
| `mojo-status-strict` | The same, and fail if a program we wrote fails |
|
|
| `mojo-harvest` | After editing `mojo/pin.json`: fetch Modular's sources, process, regenerate (network) |
|
|
| `mojo-harvest-local [dir]` | Harvest, with zips standing in for sources the pin leaves unresolved |
|
|
| `mojo-harvest-offline [dir]` | Harvest from zips only, no network |
|
|
| `mojo-fetch` | Re-resolve every ref in the pin and rewrite the lock (network) |
|
|
| `mojo-emit` | Regenerate `src/mojo/generated/` from the pin and corpus, offline |
|
|
| `mojo-test` | The corpus pipeline's own tests |
|
|
| `mojo-run <file>` | Run one Mojo file on the pinned local compiler |
|
|
| `mojo-probes-local` | Run every probe on the local compiler (a quick look) |
|
|
| `mojo-update` | After editing the pin: harvest, verify, status, test |
|
|
| **Ship** ([docs/deploy.md](docs/deploy.md)) | |
|
|
| `ci` | What CI runs: every test, and no program of ours failing |
|
|
| `site` | Test, then assemble `site/` |
|
|
| `package` | Zip what git tracks, and nothing it ignores, into `package/` for sharing |
|
|
| `deploy [slug] [target]` | Publish `site/` to `/srv/www/<slug>`, optionally over SSH |
|
|
|
|
## Where things are
|
|
|
|
```
|
|
AGENTS.md rules for changing the code (read first)
|
|
index.html, styles.css the page and the app's stylesheet
|
|
src/
|
|
main.ts the hash router
|
|
core/ state and its URL codec, the session, the catalog, the areas, the language reference
|
|
sync/ the translators between the languages and the hub that keeps the Bridge's panes in step
|
|
services/ one adapter per language behind LanguageService (lingo, matho, pseudo, speco, mojo, asm), godbolt.ts
|
|
mojo/ the Mojo checker, interpreter, lifetimes, and AT&T-to-Intel listing translator
|
|
mojo/generated/ generated from mojo/pin.json and the corpus; do not edit
|
|
ui/ the shell (one per area), the home page, the "With Quarto" gallery, the editor, the embeds, the views
|
|
quarto/ the Quarto extension's rendered views: a program run and drawn by the views, as HTML (render.ts),
|
|
the small document they draw into outside a browser (dom.ts), the shortcode list (shortcodes.ts)
|
|
ui/hw/ the Hardware area's machine board, over the course's x86-64 views
|
|
exercises/ one file per catalog problem
|
|
curriculum/ a lesson corpus kept as an interpreter fixture (tests/curriculum.test.mjs); no UI
|
|
engines/ the language engines this repository owns and the course copies (docs/engines.md)
|
|
vendor/ CodeMirror 6 as one built module; scripts/vendor/ rebuilds it
|
|
styles/course/ the course site's widget stylesheets, copied unchanged (and bridge.css, ours)
|
|
tests/ node --test against dist/; tests/corpus/ holds pseudo regression programs
|
|
mojo/ the Mojo corpus: the pin and lock, harvested material, our probes, local and
|
|
stress programs, and godbolt's answers (golden/)
|
|
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline (Python, standard library only)
|
|
quarto/ the Quarto extension (_extensions/pplus) and an example site using every shortcode (example/)
|
|
docs/ the documents below, and the Caddy site block
|
|
scratch/ ignored by git: a place for experiments
|
|
```
|
|
|
|
## Read next
|
|
|
|
| Document | For |
|
|
|---|---|
|
|
| [AGENTS.md](AGENTS.md) | Rules for anyone changing the code, coding agents included: the gate, what not to edit, conventions |
|
|
| [docs/app.md](docs/app.md) | What the app does: the three areas, translation between languages, its links, and how embeds behave |
|
|
| [docs/trust.md](docs/trust.md) | Every badge and verdict the app shows: what earns it, what it means, and what it does not mean |
|
|
| [docs/sync-coverage.md](docs/sync-coverage.md) | What each translator can say, written by the tests: which programs translate fully, and why the rest do not |
|
|
| [docs/exercises.md](docs/exercises.md) | Adding a catalog problem |
|
|
| [docs/mojo-corpus.md](docs/mojo-corpus.md) | Writing Mojo of our own (probes, exercise programs, stress programs) and moving to a new Mojo version |
|
|
| [docs/asm-coverage.md](docs/asm-coverage.md) | Which instructions compiled Mojo uses, against what the machine models |
|
|
| [docs/engines.md](docs/engines.md) | The language engines this repository owns, their tests, and how the course takes them |
|
|
| [docs/deploy.md](docs/deploy.md) | Building the site and publishing it to the droplet |
|
|
| [quarto/README.md](quarto/README.md) | Embedding views in a Quarto site |
|