README updated (#154)

* Update README.md for release-0.1

Co-authored-by: Yi Lin <[email protected]>

Author: Javad Amiri

README.md

@@ -1,44 +1,90 @@
 # MMTk
 
 MMTk is a framework for the design and implementation of memory managers.
-This repo hosts the Rust port of MMTk.
+This repository hosts the Rust port of MMTk.
+
+## Contents
+
+* [Requirements](#requirements)
+* [Build](#build)
+* [Usage](#Usage)
+* [Tests](#tests)
+
+## Requirements
+
+We maintain an up to date list of the prerequisite for building MMTk and its bindings in the [mmtk-dev-env](https://github.com/mmtk/mmtk-dev-env) repository.
 
 ## Build
-```bash
-cargo +nightly build --no-default-features --features <space seperated features>
+
+Building MMTk requires a nightly Rust toolchain.
+As the Rust language and its libraries (crates) are frequently evolving, we recommend using the nightly toolchain specified in the [mmtk-dev-env](https://github.com/mmtk/mmtk-dev-env).
+
+```console
+$ # replace nightly-YYYY-MM-DD with the toolchain version specified in mmtk-dev
+$ Export RUSTUP_TOOLCHAIN=nightly-YYYY-MM-DD
+
+$ cargo build --features <space separated features>
 ```
 
-The available features can be seen by examining `Cargo.toml`.
-Currently, there are two different VMs to choose from (JikesRVM and OpenJDK),
-and there are three different plans to choose from (NoGC, SemiSpace and G1).
+You must specify a GC plan as a feature at build time.
+Currently, there are two different plans to choose from:
+
+* `--features nogc` for NoGC, and
+* `--features semispace` for SemiSpace.
+
+A full list of available features can be seen by examining [`Cargo.toml`](Cargo.toml).
 By passing the `--features` flag to the Rust compiler,
-we conditionally compile VM or plan specific code.
-You can optionally enable sanity checks by add `sanity` to the set of features
+we conditionally compile plan-specific code.
+You can optionally enable sanity checks by adding `sanity` to the set of features
 you want to use.
 
 You can pass the `--release` flag to the `cargo build` command to use the
 optimizing compiler of Rust for better performance.
 
-Cross compilation can be done by using the `--target` flag.
-
 The artefact produced produced by the build process can be found under
-`target/debug` (or `target/release` for release build).
+`target/debug` (or `target/release` for the release build).
+
+[`ci-build.sh`](.github/scripts/ci-build.sh) shows the builds we builds tested by the CI.
 
 ## Usage
-The API exposed by MMTk can be found under `api/mmtk.h`.
-A client of the memory manager can use MMTk like a C library in the standard way.
-A simple example client that uses MMTk for just allocation can be found under
-`examples/main.c`.
+
+MMTk does not run standalone. You would need to integrate MMTk with a language implementation. You can either try out one of the VM bindings we have been working on, or implement your own binding in your VM for MMTk.
+
+### Try out our current bindings
+
+We maintain three VM bindings for MMTk. These bindings are accessible in the following repositories:
+
+* [OpenJDK](https://github.com/mmtk/mmtk-openjdk),
+* [JikesRVM](https://github.com/mmtk/mmtk-jikesrvm),
+* [V8](https://github.com/mmtk/mmtk-v8).
+
+For more information on these bindings, please visit their repositories.
+
+### Implement your binding
+
+MMTk provides a bi-directional interface with the language VM.
+
+1. MMTk exposes a set of [APIs](src/mm/memory_manager.rs). The language VM can call into MMTk by using those APIs.
+2. MMTk provides a trait [`VMBinding`](src/vm/mod.rs) that each language VM must implement. MMTk use `VMBinding` to call into the VM.
+
+To integrate MMTk with your language implementation, you need to provide an implementation of `VMBinding`, and
+you can optionally call MMTk's API for your needs.
 
 ## Tests
-The Rust unit tests can be found under `tests`.
-Currently,
-the CI will run all the Rust unit tests.
-The CI will also build both the 32-bit and 64-bit versions of MMTk for each plan
-to test the `alloc` function.
-
-## VM specific notes
-### JikesRVM
-Please DO NOT build MMTk manually,
-as machine generated code is involved during the build process (e.g. `src/vm/jikesrvm/entrypoint.rs` and `src/vm/jikesrvm/inc.asm`).
-Instead, please invoke the `buildit` script from JikesRVM.
+
+We use both unit tests and VM binding tests to test MMTk in the CI.
+
+### Unit tests
+
+MMTk uses Rust's testing framework for unit tests. For example, you can use the following to run unit tests for the `nogc` plan.
+
+```console
+$ cargo test --features nogc
+```
+
+A full list of all the unit tests we run in our CI can be found [here](.github/scripts/ci-test.sh).
+
+### VM binding tests
+
+MMTk is also tested with the VM bindings we are maintaining by running standard test/benchmark suites for the VMs.
+For details, please refer to each VM binding repository.