GitLab will continue to be upgraded from 11.4.5-ce.0 on November 25th 2019 at 4.00pm (AEDT) to 5.00pm (AEDT) due to Critical Security Patch Availability. During the update, GitLab and Mattermost services will not be available.

Commit 99d0d117 authored by qinsoon's avatar qinsoon

add README

parent 64dba9a5
# 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:
* rust version 1.18 (03fc9d622 2017-06-06)
* clang 4.0+
* 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).
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