search

fishjd / HappyNewMoonWithReport

Happy New Moon with Report is an open-source implementation of WebAssembly written entirely in Java. It is typically used to run or test Web Assembly Modules (*.wasm) in Java.
Apache License 2.0
40 stars 6 forks source link
java javascript wasm wasm-bytecode wasm-files wasm-modules web-assembly webassembly

readme

Happy New Moon with Report

Happy New Moon with Report is an open-source implementation of WebAssembly written entirely in Java for the JVM environment. The goal is to run wasm code on the command line or embedded in a larger application.

Happy New Moon with Report doesn't concern itself with the production of the WASM binary files; these files are produced with another tools such as Emscripten, wabt or binaryen or any of the number of languages that can output to WebAssembly such as Rust.

Happy New Moon With Report fills the same goals as WasmTime for the JVM environment.

Think of Happy New Moon With Report as the Rhino of Web Assembly. Rhino runs JavaScript in Java; Happy New Moon with Report runs WebAssembly in Java.

Happy New Moon With Report has nothing to do with reporting or fireworks.

For a list of Web Assembly languages see: Awesome WASM languages.

The basic use case is:

Wasm wasm = new Wasm("your Web Assembly Module.wasm");
wasm.exports().yourFunction();

A more concrete example.

Load HelloWorld.wasm file and call the HelloWorld() function in Java; 

Wasm wasm = new Wasm("HelloWorld.wasm");
System.out.println(wasm.exports().HelloWorld());

Goals

  1. An interpreter of *.wasm files in the Java Language
  2. Code in the Web Assembly Specification language. For example Happy New Moon With Report creates an web assembly full I32 object for the Web Assembly I32 data type. If there is a object in the Web Assembly specification there will be an analogous object in Happy New Moon With Report. Conversion to Java is 'pressed down' as far a possible in the code. This should allow causal readers of the code to understand it with only a beginning understanding of Java.
  3. Testing and Debugging should enable a large insight to the code. Each opcode is implemented individually allowing you to investigate what WebAssembly is doing.
  4. Every object has links to the Web Assembly Specification. This will explain what the code is implementing.
  5. Happy New Moon With Report is only an interpreter. No conversion from text files (.wast) to modules (.wasm).
  6. Easily embeddable in your Java project.
  7. Compatible with the Web Assembly Specification.
  8. Well commented to help casual readers.
  9. Tested with extensive unit tests.

Where to start your journey in the code

Wasm.java

The main object is in Wasm.java.
This opens the wasm module(*.wasm), parses the web assembly sections such as

WasmInstance.Java

The main loop of the interpreter is in WasmInstance.Java. In the execute(BytesFile) function an opcode is decoded and executed.

A unit test on how to load a Web Assembly module and execute a function.

See WasmAdd32Test.Java This will need to be simplified in future revisions, It is currently a bit of a mess.

The wasm module is in the add32 folder.
This folder also contains the wasm text files and notes on the bytes in the wasm module.

Testing the `HelloWorld.wasm' Web Assembly Module in JUnit.

@Test
public void testHelloWorld throws Exception {
    Wasm wasm = new Wasm("HelloWorld.wasm");
    assertEquals("Hello World", wasm.exports().HelloWorld());
}

Similar Projects

WasmTime is same for the Rust language.

For the 'Go' language: Wagon (https://github.com/go-interpreter/wagon).

A Web Assembly virtual Machine written in C/C++: WAVM (https://github.com/WAVM/WAVM).

'Life' is a secure & fast WebAssembly VM built for decentralized applications, written in Go (https://github.com/perlin-network/life).

For a list of Web Assembly Run times at Awesome WASM runtimes.

To compile Java to WebAssembly use ByteCoder

Progress

All I32 and I64 instruction are complete.
F32 Math, Bitwise, and Comparison opcodes completed. Only Conversions remain. F64 Bitwise, Comparison opcodes completed. Math and Conversions remain.

128 opcodes completed.

To do:

Branching opcodes: 9 remaining. Other opcodes: 5 remaining; Floating point opcodes: 42 remaining.

Sections

[Source] (http://webassembly.org/docs/binary-encoding/#module-structure)

Custom (a.k.a Name) section : Completed

Type Section : Completed

Import Section: To Do

Function Section: Completed

Table Section: Completed

Memory Section: Completed

Global Section: Completed

Export Section: Completed

Start Section: Completed

Code Section: See Opcodes list below.

Data Section: To Do

OpCodes Completed

[Source] (https://webassembly.github.io/spec/core/appendix/index-instructions.html)