9.0 KiB
pplus-core
pplus-core is the part of Programming+ that has to be right: the languages, the translators between them, the Mojo checker and interpreter, the prover, the fuzzer, the x86-64 machine model, and the tools that check everything it says against the ground truth in pplus-library. It has no DOM. pplus-web (the site, the editor, the views and the Quarto extension) and the course site use it as a pinned dependency.
- Languages: pseudo (parser, checker, interpreter, the English reader for lingo), matho (equations in LaTeX), speco (specifications), Mojo (a checker and an interpreter held to the real compiler), x86-64 on a model machine with caches, a pipeline and an out-of-order core.
- Translators: pseudo to Mojo, lingo, matho and speco, with line maps and located refusals, and the hub that keeps the linked languages in step (
src/sync/). - Verification: the prover (
src/engines/pseudo/logic.ts,solver.ts,vcgen.ts), sound and held to it by tests; the fuzzer (src/common/fuzz.ts); and a pinned Dafny (scripts/dafny.py). - A workspace:
src/common/workspace.tsis one piece of work and everything its sources mean. pplus-web's session extends it. - The ground truth: pplus-library, the submodule
library/, holds everything the engines are held to and nothing they run:- verified routines (statistics, numerics, alignment, molecular simulation, sequences) that a program brings in with
USE, each checked at every level (docs/library.md); - the Mojo corpus (
library/mojo/): the pin, material harvested from Modular's repositories at pinned commits, our own probes and programs, and godbolt's answers for every one of them (docs/mojo-corpus.md); - pseudo regression programs and the prover's soundness regressions (
library/pseudo/).
- verified routines (statistics, numerics, alignment, molecular simulation, sequences) that a program brings in with
- A command line:
pixi run cli check|run|prove|fuzz|translate <file>.
Everything it says about Mojo is pinned to Mojo 1.1.0 and checked against the real compiler on Compiler Explorer.
Quick start
Clone with the library submodule (git clone --recurse-submodules, or git submodule update --init in an existing clone). With pixi (it brings the pinned Mojo, Node and Python):
pixi run test # build, then every test
pixi run ci # the gate: every test, and no Mojo program of ours failing
pixi run cli prove library/pseudo/programs/27-quantifiers.pseudo
pixi run dafny-fetch # once: the pinned Dafny, into .tools/
Without pixi, with Node 20 or later (and python3 for the pipelines' tests):
npm install && npm test
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 | |
install |
Install TypeScript, the only npm dependency |
build |
Compile src/ to dist/, with type declarations for pplus-web |
watch |
Rebuild dist/ on every change |
check |
Type-check only |
test |
Build, then run every test, the pipelines' Python tests included |
cli |
pplus check|run|prove|fuzz|translate <file>: core without a browser (scripts/cli.mjs) |
engines-diff <static> |
Show what a course checkout has not taken yet from the engines (docs/engines.md) |
engines-export <static> |
Copy the engines into a course checkout, TypeScript modules as built (docs/engines.md) |
| Dafny, pinned (scripts/dafny.py) | |
dafny-fetch |
Download the pinned Dafny into .tools/, checked by SHA-256 (network, once) |
dafny |
Run the pinned Dafny with the arguments given, e.g. pixi run dafny verify file.dfy |
| The library (docs/library.md) | |
library-check |
Check every library routine at every level; writes library/status.json and STATUS.md |
library-emit |
Regenerate src/library/generated.ts, the registry USE reads, from library/ |
library-verify-mojo |
Ask the pinned Mojo compiler about every Mojo reference of the library (network) |
library-harness <id> <lang> <level> |
Print the program a reference implementation is run as |
| Write content | |
new-exercise <id> |
Start an exercise whose Mojo lives in library/mojo/local/<id>.mojo (docs/exercises.md) |
new-probe <name> <question> |
Start library/mojo/probes/<name>.mojo: one question about the compiler (docs/mojo-corpus.md) |
new-stress <name> <about> |
Start library/mojo/stress/<name>.mojo: realistic Mojo that tests the interpreter |
play <name> |
For library/mojo/local/<name>.mojo: run, verify on godbolt, build, list the assembly, test |
play-watch <name> |
The same, again on every save (tests off) |
| The Mojo corpus (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 library/mojo/golden/STATUS.md |
mojo-status-strict |
The same, and fail if a program we wrote fails |
mojo-harvest |
After editing library/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/ and library/syntax/mojo.xml 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 | |
ci |
What CI runs: every test, and no program of ours failing |
package |
Zip what git tracks, and nothing it ignores, into package/ for sharing |
Where things are
AGENTS.md rules for changing core (read first)
src/
common/ the workspace, the problem catalog, the fuzzer, the run view's data, the language
reference, the machine presets, the shared types
library/ the registry USE reads (generated from library/), and its types
engines/pseudo/ the pseudo language and the prover (logic, solver, vcgen in TypeScript), and the course's
page widgets for it (excluded from the build; see docs/engines.md)
engines/asm86/ the x86-64 model machine, and the course's widgets that draw it (views, hwviews)
engines/shared/ text helpers, and the course's DOM helpers
services/ one adapter per language behind LanguageService; the compiler request and backend
sync/ the translators and the hub that keeps the linked languages in step
mojo/ the Mojo checker, interpreter, lifetimes, practices, AT&T-to-Intel; generated/ from the corpus
exercises/ one file per catalog problem
curriculum/ a lesson corpus kept as an interpreter fixture
library/ pplus-library, a git submodule: the ground truth
modules/ verified routines that programs bring in with USE
mojo/ the Mojo corpus: the pin and lock, harvested material, our programs, godbolt's answers
pseudo/ programs/ (pseudo regression programs), prover/ (soundness regressions)
syntax/mojo.xml the Mojo words as a KDE syntax for Pandoc (generated; pplus-web copies it)
tests/ node --test against dist/, over the programs in library/ and the cases in each test
scripts/ the tasks above; scripts/mojo/ is the corpus pipeline; dafny.py the Dafny pin; cli.mjs
docs/ the documents below
Read next
| Document | For |
|---|---|
| AGENTS.md | Rules for anyone changing core, coding agents included: the gate, what not to edit, conventions |
| docs/engines.md | The engines, the prover and its soundness, and how the course takes them |
| docs/trust.md | Every verdict core produces: which tool earns it, what it means, and what it does not mean |
| docs/mojo-corpus.md | Writing Mojo of our own and moving to a new Mojo version |
| docs/library.md | The library: USE, what each check of a routine means, and changing it |
| docs/exercises.md | Adding a catalog problem |
| docs/sync-coverage.md | What each translator can say, written by the tests |
| docs/asm-coverage.md | Which instructions compiled Mojo uses, against what the machine models |