Baseline: tree as shared
This commit is contained in:
1679 files changed
+1024562
No files matched your search
@@ -0,0 +1,38 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
pixi run new-exercise rolling-sum # 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 `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](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 `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 `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.
|
||||
Reference in new issue
Block a user