# Compiler and runtime Two programs implement mtp. The {term}`compiler` turns a source file into a {term}`.mtpc`, and the {term}`runtime` turns a .mtpc into a {term}`live model` in a browser. This page defines what each program must do and must never do, the .mtpc as the only thing that passes between the two programs, and what an implementation of either program must do to conform to this spec. The format of the .mtpc is defined in {doc}`compiled-format`, and is not repeated here. ## People and artifacts Three people take part. The {term}`illustrator` writes a {term}`world model` as an `.mtp` source file. The {term}`author` writes a page and places {term}`components ` of the world model in it. The {term}`reader` opens the page and acts on the components. One person may be both the illustrator and the author. The illustrator runs the compiler on their own machine, and the runtime runs in the reader's browser. mtp requires no particular tool for making the page: the author may use any software for making web pages, an AI assistant included, and is encouraged to use the tools that they already prefer. A component is a view, a control or a listener. A {term}`view` shows the world model to the reader: a canvas draws shapes, a readout shows a line of text, and a display shows a formula. A {term}`control` is a slider, a button, a play, a stepper or a toggle, and the reader presses, drags or clicks it to change a value of the world model. A {term}`listener` is written inside a view and has no element of its own on the page: it changes a value of the world model when the reader acts on a shape or a term of that view, or when the view changes, for example when it comes into sight. The illustrator declares every component, and the author places each view and control on the page with an element of its own.
The illustrator writes the .mtp, which the compiler compiles into the .mtpc. The author writes the page. The .mtpc, the runtime script and the page make the open page in the reader’s browser, where the runtime holds one live model for each .mtpc and serves the components, which the reader sees and acts on.illustratorauthorwriteswrites.mtppagethe compilercompiles it.mtpcruntime scriptmathterpiece.jsopen page, in the reader’s browserruntimeone live model for each .mtpccomponentsviews, controls, listenerssees, acts onreader
| Artifact | Made by | What it is | |---|---|---| | the `.mtp` | the illustrator | the source of one world model | | the `.mtpc` | the compiler | the {term}`compiled model` of one world model | | the {term}`runtime script`, `mathterpiece.js` | the implementation of mtp, the same for every world model | the runtime, and the page elements that it defines | | the page | the author, with any tool for making web pages | the text, the elements that load .mtpc files, and the elements that place components | | the {term}`open page` | the reader's browser, from the page | the page with the runtime running in it, and one live model for each .mtpc that the page loads | The smallest world model that draws something has a scene with one circle and a canvas that draws the scene. This is the source smallest.mtp, 34 bytes: ```{literalinclude} pages/smallest/smallest.mtp :language: mtp ``` ```{mtpc-of} pages/smallest/smallest.mtp ``` The smallest page that shows the canvas, smallest.html, is the following, placed next to smallest.mtpc and mathterpiece.js: ```{literalinclude} pages/smallest/smallest.html :language: html ``` ```{raw} html

Open smallest.html.

``` An empty file is a world model too ({numref}`contexts-table`), but it has nothing to draw. ## The steps of compiling ```{rule} compile-steps The compiler turns a source into a .mtpc in six steps, in this order: 1. **Parse.** The {term}`parser` reads the text into {term}`forms
`, by the syntax alone ({doc}`lexical`, {doc}`grammar`). It looks up no {term}`name`. 2. **Rewrite.** Every name is resolved to its declaration ({ref}`scope`), and every {term}`sugar` form is rewritten into {term}`core forms ` ({numref}`sugar-form`). For example, `(pos [1 2])` becomes `(x 1) (y 2)`. No value is computed and no type is used. 3. **Prove.** Every {term}`expression` is given a type, and every type, {term}`range`, {term}`constraint` and other invariant that the spec requires is proved ({doc}`types`, {doc}`well-formedness`). This step proves and does nothing else. 4. **Expand.** Each `foreach` is written out as its copies, each motif instance as the {term}`body` of its motif with the arguments of the instance, and each use of a choreo as the body of its choreo with the arguments of the use. In the copies, the instances and the uses, the names built from values are replaced ({numref}`names-from-values`). 5. **Fold.** Every expression known when compiling ({doc}`binding-time`) is replaced by its value. 6. **Write.** The model is written as the .mtpc ({doc}`compiled-format`), with every type that the runtime needs. ``` So a check that the parts of a sugar form are known when compiling is made in the prove step, and every core form other than `foreach`, a motif instance and a use of a choreo reaches the fold step as it is. Which forms are sugar, and the {term}`rewrite` of each, are defined in {doc}`core`. ```{rule} prove-bodies-once The prove step proves each body once: the body of a function with each parameter ranging over every value of its declared type, the body of a `foreach` with its variable ranging over every value of its range, and the body of a motif or a choreo with each parameter ranging over every value of its declared type and constraints. An imported motif or choreo is proved once, in the file that declares it. The copies that a `foreach` makes, the instances of a motif and the uses of a choreo are not proved again. A motif or choreo body that is safe for only some values of a parameter is a {term}`compile error`, unless the parameter declares a constraint that leaves out the other values. An expression is known in the prove step when it is known when compiling ({doc}`binding-time`) and does not read, inside the body of a `foreach`, a function, a motif or a choreo, the variable of that `foreach` or a parameter of that function, motif or choreo. ``` So an error in such a body is about the body as written, and not about a copy or an instance. For example, `(motif dot ((real k)) (circle_ (r (/ 1 k))))` is a compile error at `(/ 1 k)`, since `k` may be 0, whatever the instances give for `k`. With `(real k 1 (>= 1))` as the parameter, the motif compiles. ```{rule} step-rejects-or-passes The parse, rewrite and prove steps each either reject the source or pass their output to the next step. The parse step rejects with a {term}`syntax error`, and the rewrite and prove steps with a compile error ({doc}`errors`). When a step rejects the source, no later step runs. The expand, fold and write steps never reject a source that the prove step passed, so the compiler either rejects a source or writes a .mtpc that is valid by {doc}`compiled-format`, and never both. ``` What the error of a rejected source holds is given in {numref}`conformance`. ```{rule} prover-finds-ranges To prove a range or a constraint, the {term}`prover` works out ranges ({numref}`ranges`, {numref}`range-rules`). The prover writes nothing into the model. Where the range of a bound value does not lie inside the constraint of the value, the prover gives the value a type that includes `none`, and the write step writes the `check` that this type needs ({doc}`compiled-format`). ``` So `(circle c (r (- 1 2)))` is a compile error in the prove step, since the range of `(- 1 2)` is -1 alone, and so is `(/ 1 0)`, since its divisor is 0 alone ({numref}`none-at-known-inputs`). :::{admonition} Code differs :class: note Today the rewrite, prove, expand and fold steps are not separate, and expanding comes before proving. `_Compiler.run` in mathterpiece/compiler.py, line 586, goes through the top-level forms once, and each form is rewritten, expanded, checked and {term}`folded ` as it is reached. `foreach` copies are made one at a time by `_Compiler.expand` (line 828), and the body of a motif is compiled again for each instance by `_Compiler.instance` (line 4674), so each copy and each instance is proved on its own. `_Compiler.call` (lines 1962 to 1973) folds a call and then checks its constraint against the folded value. The new middle of the compiler (mtp-08wd) follows these rules. The order of the steps and proving each body once are mtp-08wd.1. ::: ## Running the compiler ```{rule} compiler-input-output The compiler is given one source file. It reads that file and the files that it imports ({numref}`compiler-reads-files`), and then either rejects the source with an error ({numref}`conformance`) and writes no .mtpc, or writes one .mtpc for it. ``` How the compiler is run, such as the name of a command, its options, where it writes the .mtpc and what it prints, is not part of this spec ({numref}`what-is-normative`). An implementation may offer other tools with the compiler, such as a formatter for sources or a page that shows every component of a world model, and these are not part of this spec either. ## What the compiler must do and must never do The compiler resolves every name, gives every expression a type and proves it, and either rejects the source or writes a valid .mtpc, by {numref}`compile-steps` and {numref}`step-rejects-or-passes`. ```{rule} compiler-decides-early Everything that can be decided when compiling is decided when compiling, even when that makes compiling slower. Nothing that the compiler could have decided is left for the runtime to decide while the reader waits. ``` ```{rule} compiler-same-bytes The compiler is deterministic: the same source and the same imported files always give the same bytes ({doc}`compiled-format`, "Same source, same bytes"). ``` ```{rule} compiler-reads-files The compiler reads only the source file and the files that it imports, directly or through other imports. An import is looked for in the folder of the file that imports it, then in the standard {term}`library` ({ref}`scope`, {doc}`stdlib`). ``` ```{rule} compiler-never-acts-while-drawing The compiler never does what happens only while drawing ({doc}`binding-time`). It never runs a writer: it never plays an animation, never performs a write that a control or a listener would perform, and never acts as a reader would. It never reads a page, its CSS or its color scheme, and so never folds a token: a token is written with its declared value, which the runtime uses where the page gives none. ``` So the compiler never draws a random value, since a random value is known only while drawing ({numref}`random-never-folded`). ## From the .mtpc to the open page This section follows one world model from its source to an open page. It states no rule: the rules are in the sections after it and in {doc}`page-interface`. The illustrator writes the source dial.mtp: ```{literalinclude} pages/dial/dial.mtp :language: mtp ``` The compiler compiles dial.mtp into dial.mtpc, and the author writes the page dial.html: ```{literalinclude} pages/dial/dial.html :language: html ``` Below is that page, served from a folder that holds dial.html, dial.mtpc and mathterpiece.js, as the author would serve it. ```{raw} html

Open dial.html on its own.

``` When the reader opens the page, the browser and the runtime do the following, in this order: 1. The browser reads the page. The `