The gate first ran on the server that deploys the site: a slow container with no C compiler and no ICU. Ten tests failed there on correct code, and no Mojo program could be built at all. - The workflows ask for a runner labeled heavy, not the deploy server: the gate builds and runs some 300 Mojo programs and fuzzes. docs/ci.md says how to register one. With none registered a run waits. - The pinned environment has a C compiler on Linux (gcc, with its C library pinned to glibc 2.34): mojo build links with the C compiler it finds, and conda-forge's default links against a C library too old for Mojo's runtime. mojo-local reports a program that could not be linked as that, and does not keep the answer. - The pinned Dafny runs without ICU, and dafny-fetch fails when the Dafny it fetched does not start. - A test's time limit is processor time at the machine's pace (tests/helpers/pace.mjs). - The prover's time on the clock is the caller's: provePseudo and Workspace.proofBudgetMs take it, the Prove tab's 3 seconds stay the default, and the command line, library-check and the tests use none, so their answers are the counted budgets' alone. - The library pointer moves to its workflow change (e5ae090).
25 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.
The corpus itself (the pin, the harvested material, our programs and godbolt's answers) lives in pplus-library, the submodule library/, under library/mojo/; the pipeline that builds and checks it (scripts/mojo/) and what it generates for the app (src/mojo/generated/) live here. A task that changes the corpus leaves changes in both repositories: commit and push library/ first, then commit core with the new pointer (git add library) and the regenerated files.
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 | library/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 | library/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 | library/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 library/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, after the pin's build arguments (below)
# 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.
How every program is built
Mojo is built one stated way everywhere core builds a program or asks godbolt to: corpus.py verify, library-verify-mojo, the Compile button (BUILD_ARGS in src/services/godbolt.ts: the pin's arguments, then the level's), library-check, mojo-local, mojo-fuzz, mojo-run and play. The arguments are build.args in library/mojo/pin.json, each with its reason under build.why:
--target-cpu x86-64-v3. Without itmojo buildtargets the processor it runs on, and godbolt's machines differ: on 2026-11-12 every stored listing was AVX2 (ymm), and at 12:55 EST the same request forlocal/democame back with AVX-512 (zmm,kmovq,vpternlogd), instructions the model machine does not know. x86-64-v3 is AVX2, FMA, BMI1 and BMI2, with no AVX-512, so a listing is the same whichever machine answers (probes/godbolt-target-cpu). A machine that is not x86-64 (an Apple silicon Mac) cannot build for it, so there the local tools leave it out.--fp-mode contract=off. Mojo's default,contract=fast, fuses a multiply with an add or subtract into one rounding wherever the operands arrive at run time:probes/float-contract-runtime(built withcontract=faston purpose) prints -0.22222222222222224 forx * x - xwhenxcomes from stdin and -0.2222222222222222 when it is a literal the compiler works out while building. With contraction off every Float64 operation is rounded on its own, as IEEE 754 says and as the pseudo interpreter and core's Mojo interpreter compute (probes/float-contract-runtime-offprints -0.2222222222222222 twice).
A program's own # args: come after these, and an option it names replaces the pin's (the contraction probes name --fp-mode themselves). Every stored answer records the arguments it was built with (args) and is keyed by them, so a change to build.args leaves every answer unverified until pixi run mojo-verify and library-verify-mojo ask again. tests/build-args.test.mjs fails when a builder writes a code-generation flag of its own or the Python and TypeScript halves combine the arguments differently.
mojo build or mojo run on your own machine, without these arguments, targets your processor and fuses: its last digits and its listing can differ from what Programming+ shows. pixi run mojo-run <file> builds the way everything else does.
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 (after the pin's build arguments) 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 (the pin's and the program's) 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.
The compiler on your machine
Godbolt's stored answers cover the programs someone wrote down, and they need the network. pixi also installs the pinned compiler, and two tasks hold core to it directly, offline:
pixi run mojo-local # every Mojo program core holds or generates
pixi run mojo-fuzz --seed 7 --programs 50 # programs nobody wrote
pixi run mojo-fuzz --statements --seed 7 # whole programs of statements nobody wrote
mojo-local (scripts/mojo/local.mjs) builds and runs the probes, exercise programs and stress programs as written, the Mojo the translator writes for every exercise, every pseudo regression program and every library routine on its cases, and every Mojo reference of the library. For each it asks: does the checker stay silent on what the compiler accepts; does the interpreter print what the built program prints and end the same way, or decline; does the compiler accept generated Mojo, and does it print what the pseudo prints; does this compiler agree with godbolt's stored answer for the same text, arguments and stdin. Every "no" is printed, and the task fails. The differences that are right are listed in EXPECTED at the top of the script, each with its reason; a listed one that stops differing fails the pass too, so the list only shrinks. Answers are cached in .tools/mojo-local/ by compiler version, arguments, stdin and source.
mojo-fuzz (scripts/mojo/fuzz.mjs) writes typed pseudo expressions at random from the notation's operators and built-ins, one per OUTPUT line, drops the lines the pseudo itself stops on or refuses, translates the rest, builds them, and holds each printed line to the pseudo's. It reports a line the compiler rejects, a line where the built program stops, a line that prints another value, a line where the interpreter prints something else than the built program, and a checker error on an accepted program, once per shape with the smallest expression that shows it. The same seed gives the same programs. Run it with a few seeds after changing src/sync/pseudo-to-mojo.ts or src/mojo/; when it finds something, fix the rule and pin the spelling in tests/sync-mojo.test.mjs.
With --statements it writes whole programs instead (20 to 60 lines, 100 per seed by default; the generator is scripts/mojo/fuzz-programs.mjs): records, constants, FUNCTIONs and PROCEDUREs with by-value and BYREF parameters of scalars and collections, some recursive with a bound, then the main lines, built from DECLARE of every scalar, sized, collection and record type, assignment to names, elements, fields and map entries, IF and CASE, FOR with positive and negative steps, FOR EACH over lists, arrays, text, ranges, maps and sets, WHILE, REPEAT, BREAK and CONTINUE, the collection built-ins, copies changed after they are made, and a tagged OUTPUT at many points, so the first line that differs says where. The generator is typed, so most programs check as written; the pseudo's checker and a run are the filter, and a line the checker refuses, a run stops on, or the translator says it has no Mojo for is left out and the rest tried again. A program whose output changes when SET members and map keys are visited in another order is dropped, since the notation never promised an order. The report says how many programs settled, which constructs they held, every finding once per shape with its smallest program, shrunk by leaving out statements one at a time while the built program still shows the same finding (--shrink N builds at most, 80 by default), and the pseudo engine's own faults apart. --progress prints each finding as it is found; --dry only generates and settles, to measure the generator.
Two kinds of difference are counted and not reported as failures, because the compiler decides them (trust.md): numbers that differ only in their last digits (the compiled program's std.math is its own; its arithmetic is the pseudo's, since every program is built with contraction off), and, for lines that use **, exp or log2, what those lose in Mojo 1.2.0 (they are good to 9 to 13 digits). What the compiler does wrong on its own is listed in UPSTREAM in the fuzzer, with the probe that records it; read that list on every version bump.
Neither task needs or replaces godbolt. Both need a C compiler: mojo build compiles a program and has the gcc or cc it finds link it, against a C library no older than glibc 2.34. The pinned environment brings one on Linux (pixi.toml), so under pixi run the system's is not used; a program that compiles and cannot be linked is reported by mojo-local as not linked, the machine's fault and not Mojo's answer, and is not kept in its cache. A built program that traps is run with its core-dump limit set to 1, so a deliberate crash does not reach the desktop's crash handler. CI runs both in the pinned environment, which brings the compiler: pixi run ci runs mojo-local and a short mojo-fuzz, and the nightly run fuzzes longer (ci.md). Run both yourself after changing the translator, the checker or the interpreter, and after a version bump.
Reading the status
pixi run mojo-status judges every item from the stored answers, offline, and writes library/mojo/golden/STATUS.md (a table per corpus, every failure with its reason, and every probe's question and verdict) and status.json (git -C library 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 |
|---|---|---|
library/mojo/pin.json |
The Mojo version, the godbolt compiler id, the arguments every program is built with (build), each source repository and the ref to use, and the dialect markers |
You |
library/mojo/mojo.lock.json |
What each ref resolved to: commit, zip sha256, and the directory inside the zip | fetch/harvest |
library/mojo/corpus/ |
Processed material, one directory per processor, each item with its provenance | harvest |
library/mojo/corpus/SOURCES.md |
Which commit and license everything came from, what each processor found, every warning | harvest |
library/mojo/licenses/ |
Each source's license file, copied from the commit the pin's licenseCheck names |
You |
library/THIRD_PARTY.md |
Every harvested file with its source and the license header it carries, and what each license check found | emit (and harvest, verify) |
library/mojo/probes/ |
Our questions about the pinned compiler's behavior, one small program each | You (new-probe) |
library/mojo/local/ |
Exercise programs, shipped in the app | You (new-exercise) |
library/mojo/stress/ |
Realistic programs that test the interpreter, not shipped | You (new-stress) |
library/mojo/golden/<key>.json |
Godbolt's answer for one program, keyed by compiler, mode, arguments (the pin's, then the program's), stdin and source | verify; prune removes the ones nothing reads |
library/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, build arguments), tokens.ts (the words, removed words and the compiler's messages for them), editor.ts (comment and indentation rules), programs.ts (library/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 |
library/syntax/mojo.xml |
The same words as a KDE syntax for Pandoc listings (pplus-web copies it into its Quarto extension with its quarto-css task) | 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=ZIPuses a zip on disk for one source.--local-dir DIRmatches every zip in a directory to a source by its marker files, but only for sources whose ref is stillUNRESOLVED; add--offlineto let zips stand in for pinned refs too (the lock then saysstandsInFor, and the next online run fetches the real ref).harvest --processors quest,tokensreruns some processors;--keepor--workdir DIRkeeps the extracted sources for inspection.verify --item 'probes/life-*' --forceasks again about some items (pixi run mojo-verify-itemdoes this);--dry-runshows the request and the count and sends nothing;--corpus diagnosticsadds the compiler's own tests (opt-in: about 140 files);--limit Nasks about at most N.status --strictexits 1 if a program we wrote fails;--strict-corpuspicks 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
- Find the release. Mojo releases are tagged
mojo/vX.Y.Zinmodular/modular(the platform's own tags aremodular/vX.Y). Find godbolt's compiler id for it,mojo_X_Y_Z, inhttps://godbolt.org/api/compilers/mojo, and check that pixi's channel has it (pixi search -c https://conda.modular.com/max/ mojo). - Edit
library/mojo/pin.json:mojo.version,godbolt.compiler, andsources.modular.ref; andmojo = "==X.Y.Z"inpixi.toml(pplus-web's too), thenpixi install. A test holds the three names in the pin to one release, andpixi.tomland the documents to the pin. Move the other refs to the commits that match: Mojo Quest's commit whosesrc/lib/compile.tsnames the new compiler id; the vscode-mojo, mojo-syntax and skills commits released alongside it. - Review the dialect markers against the new release notes. Anything in the notes' Removed or Language changes sections belongs in
older; anything innewerthat this release now includes comes out. (newermatters only when harvesting a snapshot past a release; at a release tag it is empty, and a test says so.) pixi run mojo-harvest, then readlibrary/mojo/corpus/SOURCES.md: every warning is something to look at, and areleaseline sayingsnapshot newermeans the ref is not the release tag. A release can be tagged before its notes leave the nightly changelog (1.2.0 was: there is nov1.2.0.mdatmojo/v1.2.0); thereleaseprocessor then reads the changelog as the release's notes and saysnotesFrom nightly-changelog.pixi run mojo-verify. A new compiler id changes every key, so every item is asked again, one request each and two at a time (pixi run mojo-verify-dryprints how many). Run it once, not in a loop; the public server is shared.pixi run mojo-status, then readlibrary/mojo/golden/STATUS.md.git -C library diff mojo/golden/status.jsonshows 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. The compiler's wording changes too: the checker quotes it, andtests/mojo-check.test.mjsfails where a quoted message moved (1.2.0 names aTStringby where its values live, not by their types).- Check each moved source's license at its new commit: read the repository's license files and the headers of what was harvested, copy the license file into
library/mojo/licenses/, and update that source'slicenseCheckin the pin (commit, date, file, sha256, what it says).pixi run mojo-emitrewriteslibrary/THIRD_PARTY.md;tests/third-party.test.mjsfails until every source was checked at the commit the lock holds. pixi run mojo-local, thenpixi run mojo-fuzzwith two or three seeds: the new compiler on every program core holds or generates. Thenpixi run library-verify-mojoandpixi run library-checkfor the library's Mojo references.pixi run mojo-prune: the old pin's answers are keyed by its compiler id, so nothing reads them any more (git keeps them).pixi run test, then commit the pin, the lock, the corpus, the goldens and the library's records in pplus-library, and the new pointer,pixi.toml,pixi.lock,src/mojo/generated/andsrc/library/generated.tshere.
Licenses and provenance
Every item records its repository, commit (or local zip hash), path, and license; SOURCES.md summarizes them, and library/THIRD_PARTY.md counts every harvested file by the license header it carries and lists the ones with none (the manual's snippets, cut from pages with no header, and Mojo Quest's starters). Modular's repository files carry Apache-2.0 WITH LLVM-exception headers, and the repository's own LICENSE covers the rest, the docs included. Mojo Quest's solutions carry the same headers, but the repository has no LICENSE file, and its starters come from a module with no header, 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. |