#Starshine MoonBit library tutorial

#Terms

• WAT is the text format for a WebAssembly module.
• Wasm is the binary format for a WebAssembly module.
• Parse means to convert text to a module value.
• Validate means to check a module against WebAssembly rules.
• Optimize means to change a module while it keeps the same behavior.
• Encode means to convert a module value to binary bytes.
• Alias means a short name for an imported package.
• Result is a value that contains Ok(value) or Err(error).

#Prepare your computer

1. Install MoonBit.
2. Run this command to check the installation:

   moon version --all

3. Install a C compiler for the native procedure.
4. Run this command to check the C compiler:

   cc --version

5. On Linux, set the stack limit for native debug compilation in this terminal:

   ulimit -s 65536

#Create a program

1. Create an empty project:

   moon new answer-tool

2. Open its directory:

   cd answer-tool

3. Add the library dependency:

   moon add jtenner/starshine@0.2.2

4. Replace cmd/main/moon.pkg with this configuration:

import {
  "jtenner/starshine/wast" @wast,
  "jtenner/starshine/validate" @validate,
  "jtenner/starshine/passes" @passes,
  "jtenner/starshine/binary" @binary,
  "jtenner/starshine/fs" @fs,
}
pkgtype(kind: "executable")

#Add the library function

1. Create cmd/main/optimizer.mbt.
2. Copy this code into the file:

fn optimize_wat(text : String) -> Result[Bytes, String] {
  let input = match @wast.wast_to_binary_module(text) {
    Ok(value) => value
    Err(error) => return Err("Cannot parse WAT: \{error}")
  }
  match @validate.validate_module(input) {
    Ok(_) => ()
    Err(error) => return Err("Cannot validate input: \{error}")
  }
  let optimized = match @passes.run_hot_pipeline(
    input,
    @passes.HotPipelineOptions::new(),
    ["precompute", "vacuum"],
  ) {
    Ok(value) => value
    Err(error) => return Err("Cannot optimize module: \{error}")
  }
  match @validate.validate_module(optimized) {
    Ok(_) => ()
    Err(error) => return Err("Cannot validate output: \{error}")
  }
  match @binary.encode_module(optimized) {
    Ok(bytes) => Ok(bytes)
    Err(error) => Err("Cannot encode module: \{error}")
  }
}

#Run a complete example

1. Replace cmd/main/main.mbt with this code:

fn main {
  let text = "(module (func (export \"answer\") (result i32) i32.const 40 i32.const 2 i32.add))"
  let bytes = match optimize_wat(text) {
    Ok(value) => value
    Err(error) => abort(error)
  }
  let numbers = bytes.to_array().map(byte => byte.to_int())
  let header = [0, 97, 115, 109, 1, 0, 0, 0]
  if numbers.length() < header.length() {
    abort("Wasm output has no header.")
  }
  for index = 0; index < header.length(); index = index + 1 {
    if numbers[index] != header[index] {
      abort("Wasm output has an invalid header.")
    }
  }
  println(numbers)
  println("Wasm header is valid.")
}

2. Resolve the project dependencies:

   moon update

3. Run the WasmGC target:

   moon run cmd/main --target wasm-gc

4. Check that the first eight numbers are [0, 97, 115, 109, 1, 0, 0, 0].
5. Check that the last line is Wasm header is valid..

6. Run the native target:

   moon run cmd/main --target native

#Read a file and write Wasm

1. Create input.wat in the project directory.
2. Copy this text into the file:

(module (func (export "answer") (result i32) i32.const 40 i32.const 2 i32.add))

3. Replace cmd/main/main.mbt with this code:

fn main {
  let text = match @fs.read_file_sync("input.wat") {
    Ok(value) => value
    Err(error) => abort(error)
  }
  let bytes = match optimize_wat(text) {
    Ok(value) => value
    Err(error) => abort(error)
  }
  match @fs.write_file_bytes("answer.wasm", bytes) {
    Ok(_) => println("Wrote answer.wasm")
    Err(error) => abort(error)
  }
}

4. Run the program:

   moon run cmd/main --target native

5. Check that answer.wasm exists in the project directory.

#Handle errors

1. Change input.wat to invalid text.
2. Run the file procedure again.
3. Check the error message.
4. Restore valid WAT before the next run.

#More information