Initial commit
Test / gate (push) Failing after 19m0s

This commit is contained in:
alexm committed 2026-11-12 22:23:54 -05:00
commit 401084bab3
265 files changed
+69224

No files matched your search

+38
View File
@@ -0,0 +1,38 @@
# 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
```bash
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](mojo-corpus.md#mojo-of-our-own).
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](mojo-corpus.md#the-assembly)).
## 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.