Files
pplus-core/docs/engines.md
T
2026-10-05 03:03:38 +00:00

4.4 KiB

The vendored course code

Programming+ runs the course site's own language engines and draws the hardware views with the course's own stylesheets, so a program behaves the same in the app as on a course page.

Here From the course repository What it is
src/engines/pseudo/ static/js/pseudo/ The pseudo language: parser, checker, interpreter, the English (lingo) reader, the prover's verification conditions, translation
src/engines/asm86/ static/js/asm86/ The x86-64 model machine, its caches, pipeline and out-of-order core, and the widgets that draw them
src/engines/shared/ static/js/shared/ DOM helpers, URL state, text distance, charts
styles/course/ static/css/base/, static/css/widgets/ The widget stylesheets (styles/course/README.md)

The engines are wrapped behind one LanguageService interface (src/core/types.ts, adapters in src/services/). Modules the app does not use are excluded from the build in tsconfig.json. Do not edit src/engines/ casually: a change there is a change to the course's language.

How the copies differ from the course

pixi run engines-diff <course>/static compares every file, ignoring whitespace. As of the last check the stylesheets are identical; most engine modules differ only in formatting (they were reindented); and fourteen differ in content, every one of them a change made here and not yet sent back:

  • pseudo: the text built-ins SPLIT, JOIN, INDEX_OF, REPLACE and the numerical built-ins (FLOOR, CEIL, LOG10, SIN, COS, TAN, ATAN2, PI, the statistics) in lang, parse, check, interp, translate, vcgen; PARALLEL FOR with its race detector; an indexed read L[I] recorded as a read of one position, not all of L (interp); one reserved-name error for a keyword used as a name (parse); english.js exporting COMPARISONS and IN_PHRASES so the reference can read them; analyze.js and coach.js treating a variable passed BYREF to a procedure that writes it first as an out-parameter, not a read; and coach.js no longer warning "growing bound" on a queue drained by WHILE LENGTH(Q) > 0.
  • asm86: what compiled Mojo uses beyond the course's subset (interp.js, about 630 lines): the BMI bit instructions, atomic read-modify-writes with lock, bit tests that write, bswap, ud2, the 128-bit AVX spellings, scalar double precision, and the double-width shifts; the parity flag (interp, uops, views); the floating-point units and their latencies (uops); a small change in sandbox.js; and in hwviews.js the whole core's arrows (machineView): only a lit edge carries an arrowhead, in its own color and on the end its data reached, each view has its own marker ids, and the result's edge into the registers starts at the port that produced it.

One addition to the pseudo language lives outside the engine, in app code: DECLARE <name> : <type> <- <value>, a declaration with its starting value on one line (Mojo's var total: Int = 0). src/services/pseudo-study.ts reads it by doing what the engine's study() does (parse, check, analyze, coach) with one step between parse and check: the <- value is blanked out of the line, columns kept, so the engine parses a plain DECLARE, and the value is parsed on its own and put in as an ordinary assignment on the same line. Every app reader of pseudo (studyOf, and the lingo, matho and Mojo translators) goes through it; pseudo-to-mojo writes the pair as one var line. The two-line form reads as before. If the course takes the form into its parser, this module can go.

Deciding what happens to these (send them to the course, or make this repository the engines' home and have the course copy from here) is open; until then, engines-diff is how to see the gap.

Updating from the course

  1. pixi run engines-diff <course>/static and read the list.
  2. For a file that differs only in whitespace, or that changed only on the course side, copy the course's file over the one here.
  3. For a file that differs in content on both sides, merge by hand, keeping the changes listed above.
  4. pixi run test. The engines have no tests of their own in the course repository; the tests here (tests/services.test.mjs, tests/corpus.test.mjs, the curriculum and reference tests, tests/asm-coverage.test.mjs) are what catch a regression.
  5. For the stylesheets, follow styles/course/README.md.