README.md 3.22 KB
Newer Older
Kunshan Wang's avatar
Kunshan Wang committed
1 2
Mu Reference Implementation version 2
=====================================
Kunshan Wang's avatar
Kunshan Wang committed
3

Kunshan Wang's avatar
Kunshan Wang committed
4
This project is the current reference implementation of Mu, the micro virtual
5
machine designed by [The Micro Virtual Machine Project](http://microvm.org).
Kunshan Wang's avatar
Kunshan Wang committed
6

7 8 9 10 11 12 13
Version 2.0.x implements the [Mu Specification version
2](https://github.com/microvm/microvm-spec/wiki) revision
``92da59004e9c8d89bbafdc6b2039fb51c212ebfb``. You will need to clone the Wiki
and view it locally. [This fork of Restview](https://github.com/wks/restview)
can read the Wiki locally with ease.

This project is based on the previous works of
Kunshan Wang's avatar
Kunshan Wang committed
14
[simplest-microvm-project](https://github.com/microvm/simplest-microvm-project).
15 16
[microvm-refimpl](https://github.com/microvm-project/microvm-refimpl) is the
previous reference implementation.
Kunshan Wang's avatar
Kunshan Wang committed
17 18 19 20

How to compile
--------------

Kunshan Wang's avatar
Kunshan Wang committed
21 22 23 24 25 26 27
**For the impatient**:

* If you use Mac, install [Homebrew](http://brew.sh/).
* Install [Scala](http://scala-lang.org/) 2.11. If you use Mac and Homebrew,
  `brew install scala`.
* Install [sbt](http://www.scala-sbt.org/) 0.13. If you use Mac and Homebrew,
  `brew install sbt`.
28
* Install [Scala IDE](http://scala-ide.org/) 4.x (Eclipse with pre-installed
Kunshan Wang's avatar
Kunshan Wang committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
  plugins for Scala).
* Clone this repository:

```bash
git clone git@github.com:microvm/microvm-refimpl2.git
```

* In the directory `microvm-refimpl2`, do the following:

```bash
sbt update
sbt antlr4:antlr4Generate
sbt eclipse
```

* Open Scala IDE and import the generated project as "existing project into
  workspace".

**Detailed guide**:

49 50 51 52
You need [Scala](http://scala-lang.org/) 2.11 and
[sbt](http://www.scala-sbt.org/) 0.13. It is recommended to install them using
the package manager of your operating system or distribution (including apt-get,
yum, pacman, etc. for GNU/Linux distributions and Homebrew for Mac OS X).
Kunshan Wang's avatar
Kunshan Wang committed
53

54 55
To download all dependencies from the Maven central repository, invoke `sbt
update`.
Kunshan Wang's avatar
Kunshan Wang committed
56

57 58 59
To compile, invoke `sbt compile` or do this in your favourite IDE. This will
also generate the Mu IR parser from the Antlr grammar. The generated sources
will be in the `target/scala-2.11/src_managed` directory.
Kunshan Wang's avatar
Kunshan Wang committed
60

61
To generate an Eclipse project, install the [sbt-eclipse
62 63 64
plugin](https://github.com/typesafehub/sbteclipse) and invoke `sbt eclipse`. By
default, it should automatically put the managed source directory to the source
paths, too.
65 66 67

IntelliJ IDEA has plugins for Scala and SBT. Make sure you don't commit `.idea`
or generated project files into the repository.
Kunshan Wang's avatar
Kunshan Wang committed
68

69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
How to run
----------

There is a sample factorial program (generously provided by @johnjiabinzhang) in
the `src/test` directory. To run the program with all dependencies on the
classpath, you need to run it with sbt. Invoke `sbt` to enter the interactive
shell. Then type:

```
set fork := true
test:runMain junks.FactorialFromRPython
```

or directly from the command line:

```
sbt 'set fork:=true' 'test:runMain junks.FactorialFromRPython'
```

`fork := true` tells sbt to run the program in a different process than the one
running sbt itself.

Kunshan Wang's avatar
Kunshan Wang committed
91 92 93 94 95 96 97 98 99 100 101
Author and Copyright
--------------------

This project is created by Kunshan Wang, Yi Lin, Steve Blackburn, Antony
Hosking, Michael Norrish.

This project is released under the CC-BY-SA license. See `LICENSE`.

Contact
-------

102 103 104 105 106
Kunshan Wang <kunshan.wang@anu.edu.au>

<!--
vim: tw=80
-->