Verified Commit 874c26b4 authored by Camil Staps's avatar Camil Staps 🚀

Update documentation

parent 22c98086
Pipeline #22272 passed with stages
in 25 minutes and 38 seconds
......@@ -9,8 +9,7 @@ This repository contains the following:
optimised ABC language.
- A bytecode linker (`bclink`) which links several bytecode files together into
one.
- A bytecode stripper (`bcstrip`) which removes any dead code and all symbol
names from a bytecode file.
- A bytecode stripper (`bcstrip`) which removes dead code from a bytecode file.
- An interpreter (`interpret`) which can run bytecode files.
- A graphical debugger (`debug`) to debug bytecode files.
- A Clean library (`ABC.Interpreter`) around GraphCopy and the interpreter
......@@ -38,9 +37,19 @@ program:
- `ByteCode`: path for the main bytecode file (e.g. `{Project}*app.bc`)
- `CodeGen/GenerateByteCode`: `True`
- `CodeGen/OptimiseABC`: `True` (unless you suspect a bug in the ABC optimiser)
- `Link/StripByteCode`: `False` in most use cases
In the Clean IDE, you can set these in Project Options > Bytecode.
- `Link/StripByteCode`: `True` in most use cases (otherwise, the full bytecode
for all modules is included)
- `Link/KeepByteCodeSymbols`: `True` in most use cases (otherwise, no symbols
are present in the stripped bytecode, making GraphCopy impossible)
- `Link/PrelinkByteCode`: `True` if the bytecode is to be used by the
[WebAssembly interpreter](/doc/wasm.md), to create a separate `.pbc` file as
well.
In the Clean IDE, you can set these in Project Options > Bytecode. To better
understand the build workflow, see [tools.md](/doc/tools.md) and the diagram
below:
![build workflow](/doc/toolchain.svg)
See the documentation in [ABC.Interpreter](/lib/ABC/Interpreter.dcl) for more
details about the serialization library itself.
......
digraph {
rankdir=LR;
othermodule1 [ label="...", shape=none ];
othermodule1 -> "main.bc";
"mod.abc" -> "mod.opt.abc" [ label=<<font face="courier">abcopt</font><br/>if OptimiseABC> ];
"mod.opt.abc" -> "mod.bc" [ label=<<font face="courier">bcgen</font><br/>if GenerateByteCode<br/>and OptimiseABC> ];
"mod.abc" -> "mod.bc" [ style=dashed, label=<<font face="courier">bcgen</font><br/>if GenerateByteCode<br/> and not OptimiseABC> ];
"mod.bc" -> "main.bc" [ label=<<font face="courier">bclink</font>> ];
othermodule2 [ label="...", shape=none ];
othermodule2 -> "main.bc";
"main.bc" -> "main.bc" [ label=<<font face="courier">bcstrip</font><br/> if StripByteCode> ];
"main.bc" -> "main.pbc" [ label=<<font face="courier">bcprelink</font><br/> if PrelinkByteCode> ];
}
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.38.0 (20140413.2041)
-->
<!-- Title: %3 Pages: 1 -->
<svg width="970pt" height="152pt"
viewBox="0.00 0.00 970.27 152.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 148)">
<title>%3</title>
<polygon fill="white" stroke="none" points="-4,4 -4,-148 966.271,-148 966.271,4 -4,4"/>
<!-- othermodule1 -->
<g id="node1" class="node"><title>othermodule1</title>
<text text-anchor="middle" x="525.889" y="-122.3" font-family="Times,serif" font-size="14.00">...</text>
</g>
<!-- main.bc -->
<g id="node2" class="node"><title>main.bc</title>
<ellipse fill="none" stroke="black" cx="689.232" cy="-72" rx="39.7935" ry="18"/>
<text text-anchor="middle" x="689.232" y="-68.3" font-family="Times,serif" font-size="14.00">main.bc</text>
</g>
<!-- othermodule1&#45;&gt;main.bc -->
<g id="edge1" class="edge"><title>othermodule1&#45;&gt;main.bc</title>
<path fill="none" stroke="black" d="M553.138,-117.233C574.315,-110.158 604.871,-99.9457 631.586,-91 636.561,-89.3341 641.781,-87.5848 646.956,-85.8502"/>
<polygon fill="black" stroke="black" points="648.405,-89.0557 656.773,-82.558 646.179,-82.4189 648.405,-89.0557"/>
</g>
<!-- main.bc&#45;&gt;main.bc -->
<g id="edge7" class="edge"><title>main.bc&#45;&gt;main.bc</title>
<path fill="none" stroke="black" d="M674.702,-89.0373C671.737,-98.8579 676.58,-108 689.232,-108 697.14,-108 701.998,-104.429 703.805,-99.3529"/>
<polygon fill="black" stroke="black" points="707.303,-99.023 703.763,-89.0373 700.303,-99.0514 707.303,-99.023"/>
<text text-anchor="start" x="660.232" y="-125.8" font-family="Courier,monospace" font-size="14.00">bcstrip</text>
<text text-anchor="start" x="640.732" y="-111.8" font-family="Times,serif" font-size="14.00"> if StripByteCode</text>
</g>
<!-- main.pbc -->
<g id="node7" class="node"><title>main.pbc</title>
<ellipse fill="none" stroke="black" cx="918.075" cy="-72" rx="44.393" ry="18"/>
<text text-anchor="middle" x="918.075" y="-68.3" font-family="Times,serif" font-size="14.00">main.pbc</text>
</g>
<!-- main.bc&#45;&gt;main.pbc -->
<g id="edge8" class="edge"><title>main.bc&#45;&gt;main.pbc</title>
<path fill="none" stroke="black" d="M728.97,-72C766.067,-72 822.35,-72 863.687,-72"/>
<polygon fill="black" stroke="black" points="863.854,-75.5001 873.854,-72 863.854,-68.5001 863.854,-75.5001"/>
<text text-anchor="start" x="763.879" y="-89.8" font-family="Courier,monospace" font-size="14.00">bcprelink</text>
<text text-anchor="start" x="746.879" y="-75.8" font-family="Times,serif" font-size="14.00"> if PrelinkByteCode</text>
</g>
<!-- mod.abc -->
<g id="node3" class="node"><title>mod.abc</title>
<ellipse fill="none" stroke="black" cx="41.5963" cy="-60" rx="41.6928" ry="18"/>
<text text-anchor="middle" x="41.5963" y="-56.3" font-family="Times,serif" font-size="14.00">mod.abc</text>
</g>
<!-- mod.opt.abc -->
<g id="node4" class="node"><title>mod.opt.abc</title>
<ellipse fill="none" stroke="black" cx="273.693" cy="-111" rx="55.4913" ry="18"/>
<text text-anchor="middle" x="273.693" y="-107.3" font-family="Times,serif" font-size="14.00">mod.opt.abc</text>
</g>
<!-- mod.abc&#45;&gt;mod.opt.abc -->
<g id="edge2" class="edge"><title>mod.abc&#45;&gt;mod.opt.abc</title>
<path fill="none" stroke="black" d="M79.0558,-68.0811C116.245,-76.3239 174.42,-89.2182 217.304,-98.7234"/>
<polygon fill="black" stroke="black" points="216.784,-102.193 227.305,-100.94 218.299,-95.3589 216.784,-102.193"/>
<text text-anchor="start" x="121.693" y="-110.8" font-family="Courier,monospace" font-size="14.00">abcopt</text>
<text text-anchor="start" x="101.193" y="-96.8" font-family="Times,serif" font-size="14.00">if OptimiseABC</text>
</g>
<!-- mod.bc -->
<g id="node5" class="node"><title>mod.bc</title>
<ellipse fill="none" stroke="black" cx="525.889" cy="-72" rx="37.8943" ry="18"/>
<text text-anchor="middle" x="525.889" y="-68.3" font-family="Times,serif" font-size="14.00">mod.bc</text>
</g>
<!-- mod.abc&#45;&gt;mod.bc -->
<g id="edge4" class="edge"><title>mod.abc&#45;&gt;mod.bc</title>
<path fill="none" stroke="black" stroke-dasharray="5,2" d="M81.4457,-54.6357C115.353,-50.2394 165.921,-44.3706 210.193,-42 266.556,-38.9819 280.925,-37.5317 337.193,-42 386.807,-45.94 443.109,-55.6502 480.998,-62.9641"/>
<polygon fill="black" stroke="black" points="480.689,-66.4701 491.175,-64.9567 482.034,-59.6005 480.689,-66.4701"/>
<text text-anchor="start" x="252.693" y="-73.8" font-family="Courier,monospace" font-size="14.00">bcgen</text>
<text text-anchor="start" x="216.193" y="-59.8" font-family="Times,serif" font-size="14.00">if GenerateByteCode</text>
<text text-anchor="start" x="210.193" y="-45.8" font-family="Times,serif" font-size="14.00"> and not OptimiseABC</text>
</g>
<!-- mod.opt.abc&#45;&gt;mod.bc -->
<g id="edge3" class="edge"><title>mod.opt.abc&#45;&gt;mod.bc</title>
<path fill="none" stroke="black" d="M323.825,-103.341C369.015,-96.2972 435.491,-85.9352 479.467,-79.0804"/>
<polygon fill="black" stroke="black" points="480.245,-82.5014 489.587,-77.5029 479.167,-75.5849 480.245,-82.5014"/>
<text text-anchor="start" x="391.693" y="-129.8" font-family="Courier,monospace" font-size="14.00">bcgen</text>
<text text-anchor="start" x="355.193" y="-115.8" font-family="Times,serif" font-size="14.00">if GenerateByteCode</text>
<text text-anchor="start" x="361.693" y="-101.8" font-family="Times,serif" font-size="14.00">and OptimiseABC</text>
</g>
<!-- mod.bc&#45;&gt;main.bc -->
<g id="edge5" class="edge"><title>mod.bc&#45;&gt;main.bc</title>
<path fill="none" stroke="black" d="M563.905,-72C586.291,-72 615.096,-72 639.342,-72"/>
<polygon fill="black" stroke="black" points="639.422,-75.5001 649.422,-72 639.422,-68.5001 639.422,-75.5001"/>
<text text-anchor="start" x="581.586" y="-75.8" font-family="Courier,monospace" font-size="14.00">bclink</text>
</g>
<!-- othermodule2 -->
<g id="node6" class="node"><title>othermodule2</title>
<text text-anchor="middle" x="525.889" y="-14.3" font-family="Times,serif" font-size="14.00">...</text>
</g>
<!-- othermodule2&#45;&gt;main.bc -->
<g id="edge6" class="edge"><title>othermodule2&#45;&gt;main.bc</title>
<path fill="none" stroke="black" d="M553.171,-26.7962C578.602,-35.3078 617.532,-48.3373 647.074,-58.2247"/>
<polygon fill="black" stroke="black" points="646.106,-61.5914 656.7,-61.4463 648.327,-54.9533 646.106,-61.5914"/>
</g>
</g>
</svg>
......@@ -31,13 +31,25 @@ bcgen "$CLEAN_HOME/lib/StdEnv/Clean System Files/_system.opt.abc" -o "$CLEAN_HOM
bclink "Clean System Files/fsieve.obc" "$CLEAN_HOME/lib/StdEnv/Clean System Files/StdReal.obc" "$CLEAN_HOME/lib/StdEnv/Clean System Files/_system.obc" -o fsieve.bc
```
Optionally, this bytecode is stripped to remove symbol names and dead code:
Optionally, this bytecode is stripped to remove dead code and, optionally,
symbol names:
```bash
bcstrip fsive.bc -o fsieve.bc
bcstrip [-s] fsieve.bc -o fsieve.bc
```
The resulting bytecode file can be run in the interpreter or the debugger.
One can also prelink the bytecode file for use in the [WebAssembly
interpreter](/doc/wasm.md):
```bash
bcprelink fsieve.bc -o fsieve.pbc
```
The process is described in the image below with reference to the settings in
the project file:
![build workflow](/doc/toolchain.svg)
## Detailed descriptions
......@@ -70,7 +82,9 @@ Usage: `bclink OBC [OBC ...] -o BC`
Strips bytecode, leaving only the `Start` rule and all code reachable from
there.
Usage: `bcstrip BC -o BC`
Usage: `bcstrip [-s] BC -o BC`
When `-s` is given, symbol names are removed from the bytecode as well.
### interpret
......
# WebAssembly support
There is a WebAssembly version of the interpreter which can run in modern
browsers and standalone JavaScript shells.
**TODO**: in the future, this will be used in [iTasks][] to achieve sharing of
tasks between a server and a browser client.
browsers and standalone JavaScript shells. This is used in [iTasks][] to
interact with the browser DOM directly from Clean.
## Tools
Because there is no WebAssembly parser one needs to use `bcprelink` to produce
a version of the bytecode which can readily be copied into WebAssembly's linear
memory. This is done with:
The WebAssembly interpreter assumes a prelinked bytecode file with the program
memory starting at address `0x8` and the data memory starting eight bytes after
the program memory. This file is produced by `bcprelink`:
```bash
bcprelink MODULE.bc -o MODULE.ubc
bcprelink MODULE.bc -o MODULE.pbc
```
**TODO**: add support to `cpm`/the IDE for this.
In `cpm` and the Clean IDE, bytecode prelinking can be triggered using the
`Link.PrelinkByteCode` option.
[iTasks]: https://gitlab.science.ru.nl/clean-and-itasks/iTasks-SDK
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment