Files
alexm 3ebf2e2203
Build, test, deploy / site (push) Successful in 9m10s
A light deploy job, on a core whose gate does not depend on its machine
The deploy server is a slow container with other work to do. Its job ran
core's tests, which failed there (no C compiler, no ICU, limits written
for a fast machine), so nothing was published.

- pixi run ci, which the deploy job runs, is the site's tests and core's
  mojo-status-strict at the pinned commit. Core's own tests and
  everything that builds Mojo are core's gate, on a runner of its own;
  pixi run core-test stays for moving the pointer.
- The workflow and docs/deploy.md describe the runner as it is: a new
  container for every job, not a host shell.
- core moves to b10a5c8: a pinned C compiler for the Mojo compiler to
  link with, a Dafny that starts without ICU, time limits at the
  machine's pace, and a prover whose time on the clock is the caller's
  (the Prove tab keeps its 3 seconds).
2026-11-13 06:14:46 -05:00

98 lines
8.6 KiB
Markdown

# Programming+ (pplus-web)
Programming+ takes a procedure from an idea to Mojo to the machine. It is built for a world where writing code is easy and knowing what it does is the job. It has three areas (`src/core/areas.ts`):
- **Bridge**: write the procedure as plain-English steps (**lingo**), equations written in LaTeX (**matho**), pseudocode precise enough to run, prove and translate (**pseudo**), or a specification you prove against (**speco**); the others follow as you type, and Mojo is generated from the pseudo, always labeled as generated.
- **Developer**: Mojo only. The checker's advice as you type; every step and every value of the Mojo that Programming+'s interpreter reads (a subset of the language: it says why when it declines a program) in one Run view; a fuzzer that lists what it tried; and the real Mojo compiler's answer, from godbolt.org.
- **Hardware**: the code beside a board you arrange, on a model machine: registers, memory, the stack, cache lines, the caches, virtual memory, the pipeline and the out-of-order core, with Mojo and its x86-64 as tabs, linked line by line. Its cycle counts are a teaching model, not a measurement of a real processor.
A library of verified routines (statistics, numerics, sequence alignment, molecular simulation, sequences, special functions; `#/library`) comes with it, each one usable by name with `USE` and open to step through, and so does a catalog of worked problems, each opening in every area it has something to show in, and any view can be shared as a link or embedded in a page. With Quarto, a page can also run a program kept beside it while the page renders, and show the run, a stepper, the flowchart, the proof and the rest without an iframe, down to the machine itself (registers, caches, the pipeline, the core, stepped). The **With Quarto** page (`#/quarto`) is a gallery of every shortcode.
It is a static single-page app: TypeScript compiled by `tsc`, no bundler, no framework, and no npm runtime dependency (CodeMirror 6 is vendored as one built module, `src/vendor/`). The site serves its own fonts and asks no other host for anything, except that Compile & run sends the Mojo pane and its input to godbolt.org, after asking the first time. This repository is the site; what programs mean (the languages, the translators, the Mojo checker and interpreter, the prover, the fuzzer, the machine model, and the stored answers of the real tools) is **pplus-core**, a project of its own, kept here as the git submodule `core/` and imported as `#core/...` ([core/README.md](core/README.md)). Everything it says about Mojo is pinned to **Mojo 1.2.0**: core's checker and interpreter are held to the real compiler's answers ([Compiler Explorer](https://godbolt.org)) on every program in core's corpus, and Compile & run asks the compiler about any other.
## Quick start
Clone with the submodule (`git clone --recurse-submodules`, or `git submodule update --init` in an existing clone). With [pixi](https://pixi.sh) (it brings the pinned Mojo, Node and Python):
```bash
pixi run dev # build, then serve on http://localhost:4173
pixi run test # build, then every test
```
Without pixi, with Node (pixi pins 26; `package.json` asks for 20 or later, which nothing tests), `python3` for `npm run dev`'s server, and pandoc 3 for the Quarto extension's tests (without it they are skipped and say so):
```bash
npm install && npm test
npm run dev
```
## Commands
Every command is a pixi task (`pixi task list` shows them with their descriptions). `tests/tasks.test.mjs` fails if this table and `pixi.toml` disagree. Core's own commands (the Mojo corpus, `play`, the CLI, the pinned Dafny) are in [core/README.md](core/README.md) and run with `pixi run --manifest-path core/pixi.toml <task>`.
| Task | What it does |
|---|---|
| **Build and test the site** | |
| `install` | Install TypeScript, the only npm dependency |
| `core-build` | Build pplus-core (`core/`) into `core/dist/`, which the site imports as `#core/` |
| `core-test` | Run pplus-core's own tests at the pinned commit, before moving the pointer (the deploy job does not run them) |
| `core-status` | Core's `mojo-status-strict` at the pinned commit: no Mojo program of ours fails (offline) |
| `build` | Build core, then compile `src/` to `dist/` |
| `watch` | Rebuild `dist/` on every change |
| `check` | Type-check only |
| `dev` | Build, then serve on http://localhost:4173 |
| `test` | Build, then run every test of the site |
| `check-pages <dir>` | Run every program embedded in the Quarto pages under a folder ([quarto/README.md](quarto/README.md)) |
| **Quarto** | |
| `quarto-export <name> <dir>` | Copy a `core/library/mojo/local/` program, its x86-64 and setup beside a Quarto page, and print the shortcode |
| `quarto-css` | Regenerate the extension's generated files (a test fails while they are out of date) |
| `quarto-engine <dir>` | Copy a built Programming+ and core into a site's `_extensions/pplus/engine`, for the rendered views ([quarto/README.md](quarto/README.md)) |
| `quarto-example` | Render the example site in `quarto/example`, every shortcode on real pages (needs Quarto) |
| **Ship** ([docs/deploy.md](docs/deploy.md)) | |
| `ci` | What the deploy job runs before it publishes: every test of the site, and core's `mojo-status-strict` at the pinned commit |
| `release-check` | Is the chain web → core → library consistent: each pointer checked out, clean and on its pushed branch, generated files current, Mojo pinned alike |
| `release-bump` | After a change in `core/library` or `core`: move the pointers bottom up, regenerate, run each gate, print what to push in order (`--commit` commits; nothing pushes) |
| `site` | Test, then assemble `site/` |
| `caddy-check` | Serve the assembled `site/` with a real Caddy under `docs/Caddyfile` and hold its headers, caching and missing-path answers |
| `package` | Zip what git tracks, and nothing it ignores, into `package/` for sharing |
| `deploy [slug] [target]` | Publish `site/` to `/srv/www/<slug>`, optionally over SSH |
## Where things are
```
AGENTS.md rules for changing the site (read first)
index.html, styles.css the page (with the import map that points #core/ at core/dist/) and the app's stylesheet
core/ pplus-core, a git submodule: languages, translators, prover, corpus, and the library
(pplus-library, its own submodule core/library) (core/README.md)
src/
main.ts the hash router
core/ the app's state and its URL codec, the session (a core Workspace with storage, versions,
compiles and the helper), the catalog with areas, the areas, saved versions, preferences
ui/ the shell (one per area), the home page, the library, the "With Quarto" gallery, the editor, the embeds, the views
ui/hw/ the Hardware area's machine board, over the course's x86-64 views (from core)
quarto/ the Quarto extension's rendered views: a program run and drawn by the views, as HTML (render.ts),
the small document they draw into outside a browser (dom.ts), the shortcode list (shortcodes.ts)
vendor/ CodeMirror 6 as one built module; scripts/vendor/ rebuilds it
styles/course/ the course site's widget stylesheets, copied unchanged (and bridge.css, ours)
tests/ node --test against dist/ (and core/dist/)
scripts/ the tasks above
quarto/ the Quarto extension (_extensions/pplus) and an example site using every shortcode (example/)
docs/ the documents below, and the Caddy site block
scratch/ ignored by git: a place for experiments
```
## Read next
| Document | For |
|---|---|
| [AGENTS.md](AGENTS.md) | Rules for anyone changing the site, coding agents included: the gate, what not to edit, conventions |
| [docs/app.md](docs/app.md) | What the app does: the three areas, translation between languages, its links, and how embeds behave |
| [docs/deploy.md](docs/deploy.md) | Building the site and publishing it to the droplet |
| [quarto/README.md](quarto/README.md) | Embedding views in a Quarto site |
| [core/README.md](core/README.md) | pplus-core: the engines, the prover, the Mojo corpus, the CLI, the pinned Dafny, and their docs |
| [core/docs/trust.md](core/docs/trust.md) | Every badge and verdict the app shows: what earns it, what it means, and what it does not mean |
## License
Copyright 2026 Scientific Computing Studio, LLC, under the Apache License 2.0 ([LICENSE.md](LICENSE.md)); [NOTICE.md](NOTICE.md) has the notices and a disclaimer of affiliation with Modular, and [THIRD_PARTY.md](THIRD_PARTY.md) lists what is not ours and its licenses.