tools.md 3.32 KB
Newer Older
Camil Staps's avatar
Camil Staps committed
1 2
# Tools

Camil Staps's avatar
Camil Staps committed
3 4 5 6
This page gives an overview of the tools used to generate bytecode.
Because this workflow is implemented in `cpm` and the Clean IDE, you probably
do not need to know the details. This page is here for documentation purposes
only; see the [README](/README.md) for instructions for typical use cases.
Camil Staps's avatar
Camil Staps committed
7

Camil Staps's avatar
Camil Staps committed
8 9
All tools can be built by running `make -C src all`, or
`make -C src optimized all` to enable compiler optimizations.
Camil Staps's avatar
Camil Staps committed
10

Camil Staps's avatar
Camil Staps committed
11
## General build workflow
Camil Staps's avatar
Camil Staps committed
12

Camil Staps's avatar
Camil Staps committed
13 14
E.g., to generate bytecode for `fsieve.icl` which uses `StdReal` and the
`_system` standard run-time system, `cpm` performs the following steps:
Camil Staps's avatar
Camil Staps committed
15 16 17 18 19 20

```bash
# Generate all required ABC code
clm fsieve

# Optimise ABC code
21 22
abcopt "Clean System Files/fsieve.abc" -o "Clean System Files/fsieve.opt.abc"
abcopt "$CLEAN_HOME/lib/StdEnv/Clean System Files/StdReal.abc" -o "$CLEAN_HOME/lib/StdEnv/Clean System Files/StdReal.opt.abc"
Camil Staps's avatar
Camil Staps committed
23
abcopt "$CLEAN_HOME/lib/StdEnv/Clean System Files/_system.abc" -o "$CLEAN_HOME/lib/StdEnv/Clean System Files/_system.opt.abc"
Camil Staps's avatar
Camil Staps committed
24 25

# Generate bytecode
26 27
bcgen "Clean System Files/fsieve.opt.abc" -o "Clean System Files/fsieve.obc"
bcgen "$CLEAN_HOME/lib/StdEnv/Clean System Files/StdReal.opt.abc" -o "$CLEAN_HOME/lib/StdEnv/Clean System Files/StdReal.obc"
Camil Staps's avatar
Camil Staps committed
28
bcgen "$CLEAN_HOME/lib/StdEnv/Clean System Files/_system.opt.abc" -o "$CLEAN_HOME/lib/StdEnv/Clean System Files/_system.obc"
Camil Staps's avatar
Camil Staps committed
29 30

# Link bytecode
Camil Staps's avatar
Camil Staps committed
31 32
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
```
33

Camil Staps's avatar
Camil Staps committed
34 35
Optionally, this bytecode is stripped to remove dead code and, optionally,
symbol names:
Camil Staps's avatar
Camil Staps committed
36

Camil Staps's avatar
Camil Staps committed
37
```bash
Camil Staps's avatar
Camil Staps committed
38
bcstrip [-s] fsieve.bc -o fsieve.bc
Camil Staps's avatar
Camil Staps committed
39 40
```

Camil Staps's avatar
Camil Staps committed
41
The resulting bytecode file can be run in the interpreter or the debugger.
Camil Staps's avatar
Camil Staps committed
42 43 44 45 46 47 48 49 50 51 52
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)
Camil Staps's avatar
Camil Staps committed
53

Camil Staps's avatar
Camil Staps committed
54 55
## Detailed descriptions

56
### abcopt
Camil Staps's avatar
Camil Staps committed
57 58 59 60

Optimises ABC code. This removes unnecessary instructions, shrinks instruction
blocks, and introduces many new ABC instructions for frequently used blocks.

61
Usage: `abcopt ABC -o OABC`
Camil Staps's avatar
Camil Staps committed
62

63
### bcgen
Camil Staps's avatar
Camil Staps committed
64 65 66

Generates bytecode from ABC files.

67
Usage: `bcgen (O)ABC [(O)ABC ...] -o OBC`
Camil Staps's avatar
Camil Staps committed
68

69
In principle, `bcgen` can handle multiple ABC files and link them together.
Camil Staps's avatar
Camil Staps committed
70 71 72
However, this is not used any more since we have a linker. Thus, it is safer to
generate bytecode for every tool separately and link them together with `link`.

73
### bclink
Camil Staps's avatar
Camil Staps committed
74 75

Links bytecode files together.
76
The first OBC file is supposed to be that of the main module.
Camil Staps's avatar
Camil Staps committed
77

78
Usage: `bclink OBC [OBC ...] -o BC`
Camil Staps's avatar
Camil Staps committed
79

80 81 82 83 84
### bcstrip

Strips bytecode, leaving only the `Start` rule and all code reachable from
there.

Camil Staps's avatar
Camil Staps committed
85 86 87
Usage: `bcstrip [-s] BC -o BC`

When `-s` is given, symbol names are removed from the bytecode as well.
88

Camil Staps's avatar
Camil Staps committed
89 90
### interpret

91
Interprets bytecode.
Camil Staps's avatar
Camil Staps committed
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106

Usage: `interpret BC`

There are command-line options available for stack and heap size and other
settings; see `interpret -h` for details.

### debug

An interactive debugger GUI for bytecode, similar to GDB.

Usage is just like with `interpret` (i.e. `debug BC`). Not all command-line
options available for `interpret` are available for `debug`; see `debug -h` for
details.

For help on the interface, press <kbd>?</kbd> in the GUI.