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: ...@@ -9,8 +9,7 @@ This repository contains the following:
optimised ABC language. optimised ABC language.
- A bytecode linker (`bclink`) which links several bytecode files together into - A bytecode linker (`bclink`) which links several bytecode files together into
one. one.
- A bytecode stripper (`bcstrip`) which removes any dead code and all symbol - A bytecode stripper (`bcstrip`) which removes dead code from a bytecode file.
names from a bytecode file.
- An interpreter (`interpret`) which can run bytecode files. - An interpreter (`interpret`) which can run bytecode files.
- A graphical debugger (`debug`) to debug bytecode files. - A graphical debugger (`debug`) to debug bytecode files.
- A Clean library (`ABC.Interpreter`) around GraphCopy and the interpreter - A Clean library (`ABC.Interpreter`) around GraphCopy and the interpreter
...@@ -38,9 +37,19 @@ program: ...@@ -38,9 +37,19 @@ program:
- `ByteCode`: path for the main bytecode file (e.g. `{Project}*app.bc`) - `ByteCode`: path for the main bytecode file (e.g. `{Project}*app.bc`)
- `CodeGen/GenerateByteCode`: `True` - `CodeGen/GenerateByteCode`: `True`
- `CodeGen/OptimiseABC`: `True` (unless you suspect a bug in the ABC optimiser) - `CodeGen/OptimiseABC`: `True` (unless you suspect a bug in the ABC optimiser)
- `Link/StripByteCode`: `False` in most use cases - `Link/StripByteCode`: `True` in most use cases (otherwise, the full bytecode
for all modules is included)
In the Clean IDE, you can set these in Project Options > Bytecode. - `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 See the documentation in [ABC.Interpreter](/lib/ABC/Interpreter.dcl) for more
details about the serialization library itself. 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 ...@@ -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 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 ```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. 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 ## Detailed descriptions
...@@ -70,7 +82,9 @@ Usage: `bclink OBC [OBC ...] -o BC` ...@@ -70,7 +82,9 @@ Usage: `bclink OBC [OBC ...] -o BC`
Strips bytecode, leaving only the `Start` rule and all code reachable from Strips bytecode, leaving only the `Start` rule and all code reachable from
there. 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 ### interpret
......
# WebAssembly support # WebAssembly support
There is a WebAssembly version of the interpreter which can run in modern There is a WebAssembly version of the interpreter which can run in modern
browsers and standalone JavaScript shells. browsers and standalone JavaScript shells. This is used in [iTasks][] to
interact with the browser DOM directly from Clean.
**TODO**: in the future, this will be used in [iTasks][] to achieve sharing of
tasks between a server and a browser client.
## Tools ## Tools
Because there is no WebAssembly parser one needs to use `bcprelink` to produce The WebAssembly interpreter assumes a prelinked bytecode file with the program
a version of the bytecode which can readily be copied into WebAssembly's linear memory starting at address `0x8` and the data memory starting eight bytes after
memory. This is done with: the program memory. This file is produced by `bcprelink`:
```bash ```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