GitLab will be upgraded on 30 Jan 2023 from 2.00 pm (AEDT) to 3.00 pm (AEDT). During the update, GitLab and Mattermost services will not be available. If you have any concerns with this, please talk to us at N110 (b) CSIT building.

README.md 3.72 KB
Newer Older
qinsoon's avatar
qinsoon committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Zebu VM (a fast implementation of Mu Micro VM)

[![build status](https://gitlab.anu.edu.au/mu/mu-impl-fast/badges/master/build.svg)](https://gitlab.anu.edu.au/mu/mu-impl-fast/commits/master)

Mu Micro VM is a substrate language virtual machine. Mu executes its
language-/platform-neutural immediate representation to provide common
low-level abstractions for programming language implementation, such as
machine code generation and execution, garbage collection and concurrency.
With Mu, language developers only need to care about language-specific
optimisation and execution while leaving the low-level part to Mu Micro VM.

Zebu VM is a fast implementation of Mu, developed in Australia National
University.

## Platform support

Zebu supports the follow platforms:
* x86_64/linux (CI)
* aarch64/linux
* x86_64/macos (macOS 10.12+)

## Mu specification coverage

Zebu does not implement full Mu specification yet.
[This label](https://gitlab.anu.edu.au/mu/mu-impl-fast/issues?label_name%5B%5D=spec+coverage)
in the issue tracker keeps track of unimplemented features, or features that
are not compliant to Mu spec.

## Building

You will need:
qinsoon's avatar
qinsoon committed
32
* rust version 1.19 (0ade33941 2017-07-17)
qinsoon's avatar
qinsoon committed
33
* clang 4.0+
34
* cmake 3.8+ (we do not depend on cmake, but some Rust crates use it)
qinsoon's avatar
qinsoon committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
* internet connection (as Rust will download dependencies)

To build Zebu with release build,
```
  cd path/to/zebu
  MU_ZEBU=. CC=clang cargo build --release
```
you will get shared and static libraries for Zebu under `target/release/`
that you can link against in your language implementation.

You can also build Zebu in debug.
```
  cd path/to/zebu
  MU_ZEBU=. CC=clang cargo build
```

## Testing

Zebu repository includes two test suites:
* cargo test
* pytest

#### Running tests with cargo test

```
  cd path/to/zebu
  MU_ZEBU=. CC=clang RUST_TEST_THREADS=1 cargo test --release 2>/dev/null
```

#### Running tests with pytest

To facilitate tests, Zebu uses RPython (which targets Mu as backend) for some
of tests in this suite.

Download [PyPyMu](https://gitlab.anu.edu.au/mu/mu-client-pypy)
```
  cd path/to/zebu
  git clone https://gitlab.anu.edu.au/mu/mu-client-pypy.git tests/test_jit/mu-client-pypy
  cd tests/test_jit/mu-client-pypy
  git checkout mu-rewrite
  git apply pypy.patch
```

Download [RPySOM](https://github.com/microvm/RPySOM)
```
  cd path/to/zebu
  git clone https://gitlab.anu.edu.au/mu/x-RPySOM.git tests/test_jit/RPySOM
  cd tests/test_jit/RPySOM
  git submodule init
  git submodule update
```

Running pytest (you will need Python 2.7 with pytest module)
```
  cd path/to/zebu/tests/test_jit
  export DYLD_LIBRARY_PATH=.
  export MU_ZEBU=path/to/zebu
  export MU_LOG_LEVEL=none
  export PYTHONPATH=mu-client-pypy:RPySOM/src
  export RPYSOM=RPySOM
  export ZEBU_BUILD=release
  export CC=clang
  export SPAWN_PROC=1
  python2 -m pytest test*.py -v
```

## Using Zebu for your language implementation

Zebu provides the C binding for its API declared in
[mu-fastimpl.h](src/vm/api/mu-fastimpl.h). The APIs are defined
in [Mu specification](https://gitlab.anu.edu.au/mu/mu-spec).
The header also includes Zebu-specific APIs, such as `mu_fastimpl_new()`.

Zebu allows the user to set options when creating a new instance.
The options can be found in [vm_options.rs](src/vm/vm_options.rs).

## Bug reports

As Zebu is still in its early development, we expect bugs and
missing features. We appreciate if you can report to
[Issues](https://gitlab.anu.edu.au/mu/mu-impl-fast/issues).
Our priority for Zebu development is driven by the issue tracker along with
two client implementations that are being actively developed in ANU,
[PyPy-Mu](https://gitlab.anu.edu.au/mu/mu-client-pypy)
and [GHC-Mu](https://gitlab.anu.edu.au/mu/mu-client-ghc).

## License

Zebu uses Apache 2.0. See the [license](LICENSE).