Files
pplus-web/docs/mojo-corpus.md
T
2026-10-05 03:03:38 +00:00

14 KiB

The Mojo corpus

Programming+ teaches what Mojo does when it runs, so everything it says about Mojo has to be true of a real compiler at a known version. The corpus is how: material harvested from Modular's own repositories at pinned commits, plus small programs of our own, every one of them checked on the real compiler through Compiler Explorer (godbolt). The pipeline is Python, standard library only, in scripts/mojo/ (corpus.py is its command line); Node is needed for one processor (Mojo Quest keeps its tickets in TypeScript).

Every command below is a pixi task; the README lists them all.

Mojo of our own

There are three kinds of Mojo program we write, and each has a folder, a task to start one, and a job:

Kind Folder Start one Its job Shipped in the app
probe mojo/probes/ pixi run new-probe <name> "<question>" Ask the pinned compiler one question (what does // do on a negative Int?). Godbolt's answer is the point; it is recorded, not judged. no, but the checker and interpreter are held to the answers
exercise program mojo/local/ pixi run new-exercise <id> The Mojo of a catalog problem. It must pass its own # expect-stdout: lines. yes, in src/mojo/generated/programs.ts, badged verified when it passed
stress program mojo/stress/ pixi run new-stress <name> "<what it exercises>" Realistic Mojo that stresses the interpreter. Its # expect-stdout: lines are the interpreter's prediction; godbolt confirms or refutes it. no

The loop is the same for all three:

pixi run new-probe int-floordiv-negative "does // floor toward negative infinity on Int?"
# edit mojo/probes/int-floordiv-negative.mojo
pixi run mojo-verify-item 'probes/int-floordiv-negative'   # ask godbolt (network)
pixi run test                                               # the checker and interpreter scoreboards read the new answer

For an exercise program, pixi run play <id> does the whole loop in one pass (below).

The header

A program starts with comment lines that corpus.py verify reads. Only these keys are header lines; the program starts at the first other line, and the Mojo pane hides the header.

# probe: what does // do on negative Int?   the question, or what the program shows (one line)
# stdin: 3\n4\n                           what input() reads, with \n escapes
# mode: run                                 run | asm | both (asm and both also return the listing)
# args: -O0                                 compiler arguments
# expect-stdout: -4                         a line the program must print (repeatable); implies expect: pass
# expect: compile-error                     pass | fail | compile-error | observe (the default without expect-stdout)
# origin: where the program came from       free text, for people
# status: a note on its state                free text, for people

A stored answer belongs to the exact text. Godbolt's answer is keyed by the compiler, mode, arguments, stdin and the whole source, header included. Any edit, even to a comment, makes the program unverified until it is asked again. That is deliberate: a stale answer is never shown against new code.

The fast loop for an exercise program

pixi run play rolling-sum          # one pass
pixi run play-watch rolling-sum    # again on every save (tests off)

One pass is: run the file on the local mojo (pixi provides it); corpus.py verify --item local/<name> (godbolt, network); corpus.py status (offline, rewrites programs.ts); tsc; scripts/mojo/listings.mjs; the tests. A step that cannot run (no local compiler, godbolt unreachable) is reported as skipped and the pass goes on, so offline you still get the build and the tests, with the program shown as unverified rather than guessed at. node scripts/play.mjs <name> --no-verify or --no-test skips a step.

The assembly

A program whose header says # mode: both (or asm) and # args: -O0 --debug-level=line-tables makes godbolt return the compiler's listing with its answer. scripts/mojo/listings.mjs picks the first def that is not main, translates it and the user functions it calls to the x86-64 pane's syntax exactly as the Send to x86-64 pane button does (src/mojo/att.ts, simulatorSetup for the argument registers), tags each instruction ; mojo line N with the line of the program the pane shows, and writes src/mojo/generated/listings.ts. An exercise that names the program in mojoProgram and leaves sources.asm empty gets that listing and its setup. No answer for the exact source, mode and arguments means no listing; a stale answer is never reused, because the key includes the source. Without -O0 the optimizer may inline every function and the listing holds none of yours; the script says so.

Header lines (# probe:, # mode:, …) are for verify; only those keys are stripped from what the Mojo pane shows. The first line after the header block is the program.

Reading the status

pixi run mojo-status judges every item from the stored answers, offline, and writes mojo/golden/STATUS.md (a table per corpus, every failure with its reason, and every probe's question and verdict) and status.json (git diff mojo/golden/status.json shows exactly what changed).

Each item says what the pinned compiler should do with it: pass (compiles, runs, exits 0, and prints what it should or contains the idiom it should), fail (that check must not hold: a starter), compile-error (must be rejected, with each expected error at its line), observe (a probe: the answer is the point), or skip (with a reason: newer syntax than the pin, no main, not reproducible on public godbolt). Verdicts are pass, fail, observed, skipped, and unverified (no golden yet).

The dialect markers in the pin are a cheap first look: newer patterns are syntax that arrived after the pinned version (a manual sample using one is skipped), older patterns are syntax the pinned version rejects. They only set expectations; verify decides.

What has to pass. pixi run mojo-status-strict (and CI) fails only when a program we wrote fails: a probe, an exercise program, or a stress program. Harvested items can fail for reasons that are facts about upstream (a manual sample written for a newer compiler, a test file with no main); they are listed in STATUS.md to read, not to fix here. corpus.py status --strict --strict-corpus all holds every corpus to it.

What lives where

Path What it is Who writes it
mojo/pin.json The Mojo version, the godbolt compiler id, each source repository and the ref to use, and the dialect markers You
mojo/mojo.lock.json What each ref resolved to: commit, zip sha256, and the directory inside the zip fetch/harvest
mojo/corpus/ Processed material, one directory per processor, each item with its provenance harvest
mojo/corpus/SOURCES.md Which commit and license everything came from, what each processor found, every warning harvest
mojo/probes/ Our questions about the pinned compiler's behavior, one small program each You (new-probe)
mojo/local/ Exercise programs, shipped in the app You (new-exercise)
mojo/stress/ Realistic programs that test the interpreter, not shipped You (new-stress)
mojo/golden/<key>.json Godbolt's answer for one program, keyed by compiler, mode, arguments, stdin and source verify
mojo/golden/STATUS.md Every item's verdict against the goldens status (also harvest, verify)
src/mojo/generated/ What the app reads at run time: pin.ts (version, compiler), tokens.ts (the words, removed words and the compiler's messages for them), editor.ts (comment and indentation rules), programs.ts (mojo/local/ programs with their verdicts), stdlib.ts and types.ts (which package exports each name, which types are copyable), and listings.ts (exercise listings, written by scripts/mojo/listings.mjs during play) harvest/emit; verify and status refresh programs.ts
quarto/_extensions/pplus/syntax/mojo.xml The same words as a KDE syntax for Pandoc listings harvest/emit

Commit all of it. The stored answers are what make pixi run test and mojo-status work offline.

Commands in detail

The tasks wrap corpus.py, which takes more options than the tasks pass:

  • harvest --local NAME=ZIP uses a zip on disk for one source. --local-dir DIR matches every zip in a directory to a source by its marker files, but only for sources whose ref is still UNRESOLVED; add --offline to let zips stand in for pinned refs too (the lock then says standsInFor, and the next online run fetches the real ref).
  • harvest --processors quest,tokens reruns some processors; --keep or --workdir DIR keeps the extracted sources for inspection.
  • verify --item 'probes/life-*' --force asks again about some items (pixi run mojo-verify-item does this); --dry-run shows the request and the count and sends nothing; --corpus diagnostics adds the compiler's own tests (opt-in: about 140 files); --limit N asks about at most N.
  • status --strict exits 1 if a program we wrote fails; --strict-corpus picks other corpora.
  • GITHUB_TOKEN (any token with public read access) avoids GitHub's anonymous rate limit when resolving refs.

The processors

Processor From Produces
quest mojo-quest Each ticket's solution (must pass Mojo Quest's own check) and starter (must not)
manual modular The manual's tested code samples (must run and exit 0) and every mojo block that is a whole program followed by an output block (must print it)
diagnostics modular The compiler's expected-error/warning/note tests, each annotation resolved to its line and tagged with the pass that reports it (parser, lifetimes)
tokens modular Keywords (TokenKinds.def), soft keywords and removed words (the parser), decorators (the reference), prelude names (the stdlib)
messages modular The parser's and borrow checker's diagnostic wording and fix-its, read from their C++
release modular The pinned release notes, section by section, and whether the snapshot is the pin, newer, or older
syntax mojo-syntax The TextMate grammar's tests as plain highlighting cases
editor vscode-mojo Comments, brackets, auto-closing pairs and indentation rules
skill skills Modular's table of removed syntax and its replacements
stdindex modular Which std package exports each public name (sqrt in std.math), for the compiler's import hint; a name exported from two places is left out; and which prelude functions raise (input, atol)
stdtypes modular Each std struct's declared traits (so which are implicitly copyable) and each trait's default methods (Copyable's copy, Equatable's __eq__), for the type checks

A processor whose input files are missing at the pinned ref is skipped with a warning, and its previous output is kept.

Moving to a new Mojo version

  1. Find the release. Mojo releases are tagged mojo/vX.Y.Z in modular/modular (the platform's own tags are modular/vX.Y). Find godbolt's compiler id for it, mojo_X_Y_Z, in https://godbolt.org/api/compilers/mojo.
  2. Edit mojo/pin.json: mojo.version, godbolt.compiler, and sources.modular.ref. Move the other refs to the commits that match: Mojo Quest's commit whose src/lib/compile.ts names the new compiler id; the vscode-mojo, mojo-syntax and skills commits released alongside it.
  3. Review the dialect markers against the new release notes. Anything in the notes' Removed or Language changes sections belongs in older; anything in newer that this release now includes comes out. (newer matters only when harvesting a snapshot past a release.)
  4. pixi run mojo-harvest, then read mojo/corpus/SOURCES.md: every warning is something to look at, and a release line saying snapshot newer means the ref is not the release tag.
  5. pixi run mojo-verify. A new compiler id changes every key, so every item is asked again: about 440 requests, two at a time. Run it once, not in a loop; the public server is shared.
  6. pixi run mojo-status, then read mojo/golden/STATUS.md. git diff mojo/golden/status.json shows exactly which verdicts and probe answers changed between versions. A changed probe answer is a change Programming+'s Mojo engine has to make; a failing Mojo Quest solution or manual sample usually means a language change the markers should know about.
  7. pixi run test, then commit the pin, the lock, the corpus, the goldens, and src/mojo/generated/ together.

Licenses and provenance

Every item records its repository, commit (or local zip hash), path, and license; SOURCES.md summarizes them. Modular's repository files carry Apache-2.0 WITH LLVM-exception headers. Mojo Quest's files carry the same headers, but the repository has no LICENSE file, so its programs are used as test fixtures here; confirm with Modular before showing them to students as exercises. mojo-syntax is MIT, vscode-mojo is Apache-2.0. Manual prose is not copied into the app; hover text and quick fixes will be written in our own words and link to mojolang.org.

When something goes wrong

Message Meaning
a network proxy refused api.github.com No route to GitHub from here. Use --local-dir DIR --offline, or run elsewhere.
GitHub refused the request (403) Usually the anonymous rate limit. Set GITHUB_TOKEN.
GitHub has no ref ... The tag or commit in the pin does not exist.
the lock was made from a local zip The pin has not moved since a local harvest. Pass the same zip with --local, or set a ref.
GitHub's zip ... hashes to ... The archive for a locked commit changed. Rare; accept it with --allow-hash-change after a look.
no directory in the zip holds all of [...] The repository's layout changed. Update that source's markers in the pin.
<processor>: skipped, ... has no ... That input is missing at this ref; the previous output is kept.
the quest processor needs Node 22.6+ Node strips the TypeScript types from Mojo Quest's ticket file.