README.md 3.88 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
# The C binding of the Mu reference implementation

This directory contains the C binding so you can write the Mu client in C.  If
You write the client in a JVM language, you don't need this binding since the
reference implementation is already implemented on JVM.

## Building

Make sure you build the micro VM. Go to the parent directory and type `sbt
compile`. Then come here and type `make JAVA_HOME=/path/to/the/java/home`.

This will produce the `libmurefimpl2start.so` dynamic library that contains code
that starts the JVM and creates the MuVM instance for your client written in C.
Kunshan Wang's avatar
Kunshan Wang committed
14 15 16 17 18 19 20
This library will **hard code the classpath and the JVM library path** into the
shared object, so it only works for this particular `microvm-refimpl2`
repository you cloned. This is because as this reference implementation is a
research project, it is unlikely to install it into any well-known places such
as `/usr`. Hard-coding the JVM's `libjvm.so` path using "rpath" eliminates the
need to put the JVM library path to `LD_LIBRARY_PATH`, since JVM is seldom
installed into `/usr/lib`.
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

## Usage

The `refimpl2-config` script generates the necessary compiler and linker flags
for you. 

But you should think first: Does my client start the Mu VM, or some other
program starts the VM for me?

### Your program starts Mu

You write the client in C, and it starts the JVM and creates a micro VM
instance.

The `libmurefimpl2start.so` library contains functions (defined in
`refimpl2-start.h`) that starts the JVM and create the Mu instance for you.
Your client invokes the `mu_refimpl2_new()` function which returns a `MuVM*`.
After using, call `mu_refimpl2_close` to close it. The `mu_refimpl2_new_ex`
39 40
function provides more options (see [../README.md](../README.md) for a complete
list of options).
41 42 43

Use the `refimpl2-config` script with the `--istart` flag to indicate your
program will create the Mu reference implementation instance. Such clients need
Kunshan Wang's avatar
Kunshan Wang committed
44 45 46 47
to link against `libmurefimpl2start.so`, and it will **hard-code its location
using rpath** for the same reason why it hard-codes the classpath and JVM
locations, otherwise your executable file will require `libmurefimpl2start.so`
to be on the `LD_LIBRARY_PATH` to execute.
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

For example:

```
cc `/path/to/refimpl2-config --istart --cflags --libs` -o my_client my_client.c
```

### Other program starts Mu

You write the client in C, but some other program starts the Mu micro VM and
gives your client a pointer to the `MuVM` struct. In this case, you don't know
how the micro VM is created. You only depend on the implementation-neutral API.

In this case, all your program need is the `muapi.h` header. Use
`refimpl2-config` without the `--istart` flag will only generate the inclusion
path.

As another example, you wrote a Scala program which you call a "Mu loader". The
program creates a `MicroVM` instance, then dynamically loads your client from a
".so" file, calls one of its functions and passes the `MuVM*` pointer to it. You
can write your client like this:

```
void my_entry(MuVM* mvm) {
    ...
}
```

And compile it to a dynamic library by:

```
cc `/path/to/refimpl2-config --cflags` -fPIC -shared -o libmyclient.so my_client.c
```

## Implementation details

The `MuVM` struct has an extra non-standard function `execute()`. See
[../README.md](../README.md) for more details.

87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102
## Notes for Mac OS X

You need to download the JDK from Oracle, preferably JDK 8. Set `JAVA_HOME` to
the output of `/usr/libexec/java_home`, or wherever your preferred JRE is. The
following command should work:

```bash
export JAVA_HOME=$(/usr/libexec/java_home)
```

When you upgraded the OS X operating system, and you run `test_client`, it may
complain "No Java runtime present, requesting install" and "To use the java
command-line tool you need to install a JDK". Do what it says. Click the "More
Info..." button and install the legacy Java 6 from Apple. Your `test_client`
will still use your chosen JRE.

103 104 105
<!--
vim: tw=80
-->