README.md 3.14 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

Kunshan Wang's avatar
Kunshan Wang committed
7 8 9
Version 2.1.x implements the [master branch of the Mu
Specification](https://github.com/microvm/microvm-spec/tree/goto-with-values)
which uses the goto-with-values form.
10 11

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

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

Kunshan Wang's avatar
Kunshan Wang committed
19 20 21 22 23 24 25
**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`.
26
* Install [Scala IDE](http://scala-ide.org/) 4.x (Eclipse with pre-installed
Kunshan Wang's avatar
Kunshan Wang committed
27 28 29 30 31 32 33 34 35 36
  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
37
sbt update genSrc eclipse
Kunshan Wang's avatar
Kunshan Wang committed
38 39 40 41 42 43 44
```

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

**Detailed guide**:

45 46 47 48
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
49

50 51
To download all dependencies from the Maven central repository, invoke `sbt
update`.
Kunshan Wang's avatar
Kunshan Wang committed
52

53 54
To generate the Mu IR parser from the Antlr grammar, invoke `sbt genSrc`. The
generated sources will be in the `target/scala-2.11/src_managed` directory.
Kunshan Wang's avatar
Kunshan Wang committed
55

56
To generate an Eclipse project, install the [sbt-eclipse
57 58 59 60 61 62
plugin](https://github.com/typesafehub/sbteclipse) and invoke `sbt eclipse`.
Make sure you generate the parser before creating the Eclipse project, so that
the generated sources will be on the Eclipse build path.

To compile, invoke `sbt compile`. This will also generate the Mu IR parser using
Antlr.
63 64 65

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
66

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
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
89 90 91 92 93 94 95 96 97 98 99
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
-------

100 101 102 103 104
Kunshan Wang <kunshan.wang@anu.edu.au>

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