# Programming+ (pplus-web) Programming+ takes a procedure **from an idea to Mojo to the machine**, 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**), the notation that can completely specify any procedure (**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 in one Run view, a fuzzer that lists what it tried, and the real Mojo compiler's verdict. - **Hardware**: the code beside a board you arrange: 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. A catalog of worked problems comes with it, 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, no runtime dependencies. 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.1.0** and checked against the real compiler on [Compiler Explorer](https://godbolt.org). ## 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 20 or later (and `python3` for the corpus pipeline's tests): ```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 | 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 | | `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 ` | Run every program embedded in the Quarto pages under a folder ([quarto/README.md](quarto/README.md)) | | **Quarto** | | | `quarto-export ` | Copy a `core/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 ` | 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 CI runs: every test of the site, against the pinned core | | `site` | Test, then assemble `site/` | | `package` | Zip what git tracks, and nothing it ignores, into `package/` for sharing | | `deploy [slug] [target]` | Publish `site/` to `/srv/www/`, 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 (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 "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 |