3.0 KiB
Adding an exercise
An exercise 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.1.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 blank, the demo 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.