Files
pplus-core/docs/exercises.md
T
alexm 401084bab3
Test / gate (push) Failing after 19m0s
Initial commit
2026-11-12 22:23:54 -05:00

3.4 KiB

Adding an exercise

Programming+ takes a procedure from an idea to Mojo to the machine. An exercise is one procedure on that road, written in any of its notations: lingo (steps in plain English), matho (equations written in LaTeX), pseudo (pseudocode precise enough to run, prove and translate), speco (a specification to prove against), Mojo (Modular's programming language, pinned to version 1.2.0) and x86-64. It is a catalog problem: one file in src/exercises/, listed in src/exercises/index.ts. The home page, the problem menu, share links, embeds, and the tests pick it up from there. pixi run test checks every exercise: its pseudo parses, its call runs, its answer matches expect, and its Mojo program (if it names one) exists and prints what it should.

There are two ways to start one.

An exercise around a Mojo program

pixi run new-exercise rolling-sum      # library/mojo/local/rolling-sum.mojo, src/exercises/rolling-sum.ts, registered
pixi run play rolling-sum              # after each edit: run, verify on godbolt, build, list the assembly, test

For a title or a home-page section other than the defaults, run the script directly: node scripts/new-exercise.mjs rolling-sum --title "Rolling sum" --group "Loop forms". If library/mojo/local/rolling-sum.mojo already exists, it is kept as written and only the exercise is made.

The exercise names its program (mojoProgram: 'rolling-sum') instead of carrying the source. The Mojo pane shows the file without its header comments, and badges it "verified on Mojo 1.2.0" only when godbolt's answer for that exact source passed the file's own # expect-stdout: lines. Editing the file changes its key, so it reads as unverified until play (or mojo-verify) asks again. The header keys are in mojo-corpus.md.

With # mode: both and # args: -O0 --debug-level=line-tables in the header, godbolt also returns the listing, and play turns it into the exercise's x86-64 pane (see "The assembly" in mojo-corpus.md).

An exercise in lingo, pseudo, matho or speco

Copy src/exercises/_template.ts to <id>.ts, fill it in, import it in src/exercises/index.ts, and add it to the list (before demo, the playground, which stays last). Then pixi run test.

The fields

Field Means
id The URL (#/<area>/p/<id>): lowercase words joined by hyphens
title, group, blurb The name, the home-page section it files under (a new name makes a new section), and one or two sentences on what the student does
meta Optional: lecture, level (intro, core, advanced), tags, concepts, minutes, page (where it is taught)
sources Any of lingo, pseudo, matho, speco, asm. Pseudo is derived from lingo (or matho, written in LaTeX) when absent, and speco from the pseudo's inline contracts
mojoProgram The name of a program in library/mojo/local/, shown in the Mojo pane
call, expect The call to run, and what it should return; the tests compare them
setup, machine For assembly: the setup block (registers and memory before the run) and the machine model preset
lang The pane that opens first
area The area it opens in: bridge, dev or hw. Absent: Hardware for asm-* ids, Developer for a problem that is only a Mojo program, Bridge otherwise

src/exercises/types.ts documents each field in full.