README.md 3.26 KB
Newer Older
Camil Staps's avatar
Camil Staps committed
1 2
# ABC interpreter

Camil Staps's avatar
Camil Staps committed
3 4 5 6 7 8 9 10 11
This repository contains the following:

- An optimiser (`abcopt`) for the ABC language (the intermediate target
  language of Clean), which removes redundant blocks of code and generates a
  number of specialised instructions which are not in standard ABC.
- A bytecode generator (`bcgen`) which generates a binary format of the
  optimised ABC language.
- A bytecode linker (`bclink`) which links several bytecode files together into
  one.
Camil Staps's avatar
Camil Staps committed
12
- A bytecode stripper (`bcstrip`) which removes dead code from a bytecode file.
Camil Staps's avatar
Camil Staps committed
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
- 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
  which allows for cross-platform (de)serialization of lazy expressions.

## Usage

### Cross-platform (de)serialization

Currently, the main goal of this project is to allow cross-platform
serialization of arbitrary Clean expressions. To use it like this, you have to
grab the following [nightlies][]:

- clean-abc-interpreter
- clean-base
- clean-lib-graphcopy

This includes the tools to generate bytecode, a new version of `cpm` / the
Clean IDE that interacts with these tools, and the libraries needed for
(de)serialization.

You need to set the following project settings to generate bytecode for a Clean
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)
Camil Staps's avatar
Camil Staps committed
40 41 42 43 44 45 46 47 48 49 50 51 52
- `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)
Camil Staps's avatar
Camil Staps committed
53

Camil Staps's avatar
Camil Staps committed
54
See the documentation in [ABC.Interpreter](/lib/ABC/Interpreter.dcl) for more
Camil Staps's avatar
Camil Staps committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
details about the serialization library itself.

### Independent interpretation

The interpreter can also be used stand-alone to run Clean programs. The
interpreter is not included in the nightly builds, so besides the nightlies
mentioned above you need to build it:

```bash
git clone https://gitlab.science.ru.nl/clean-and-itasks/abc-interpreter
cd abc-interpreter
make -C src optimized interpret
```

This generates the file `src/interpret` which you can then use to run the
bytecode files generated by `cpm` (see the previous step):

```bash
./src/interpret path/to/application.bc
```

### Debugging

The graphical debugger can be used to debug Clean/ABC programs. It relies on
the CURSES library. You need to build the debugger yourself:

```bash
git clone https://gitlab.science.ru.nl/clean-and-itasks/abc-interpreter
cd abc-interpreter
make -C src debug
```

Generate the bytecode as usual (without stripping it), then use:

```bash
./src/debug path/to/application.bc
```

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

[nightlies]: https://ftp.cs.ru.nl/Clean/builds/