Building wasm2brs

All the dependencies for wasm2brs are installed within a Docker image that can be run with ./run.sh.

To build our repo:

git submodule update --init --recursive
./run.sh make

To run make without the Docker image (not recommended) be sure to install the same dependencies as listed in the Dockerfile.

Running the samples

./run.sh make doom

This will place all the output files in project/. To run, either side load the project manually or use vscode with the BrightScript Language extension. When opening our repository in vscode, running the debugger will run project/.

The samples we have are:

cmake
doom
files
mandelbrot
javascript
rust

Starting your own project

The easiest way to get started is to look in our samples directory. Specifically the cmake sample is setup to be used as a template.

If you wish to use libc/libc++, then you should use install wasienv, which comes with wasi-libc as well as helpful scripts that run clang/make/cmake/etc with the correct compiler flags and directories.

The mandelbrot sample shows how to use clang directly without wasienv and no standard libraries. Note that wasm-ld is required.

In general the process looks like:

Run your build tool of choice to output a .wasm file, typicaly in Release mode with -Oz
Run Binaryen's wasm-opt to perform wasm specific optimizations that reduce goto/labels and stack variables. This is located in build/wasm2brs/third_party/binaryen/bin/wasm-opt. The recommended optimization level is -O4
Run wasm2brs to convert into a .brs file. This is located in build/wasm2brs/wasm2brs

Rust projects

Rust is considerably easier to setup and involves changing the target of the project to wasm32-wasi and compiling with optimization level z:

opt-level = "z"

rustup target add wasm32-wasi
cargo build --target wasm32-wasi

rustc -C opt-level=z --target wasm32-wasi yourfile.rs

As mentioned above, you'll want to run wasm-opt on the output wasm file and finally wasm2brs to convert into a .brs file.

Note: Some Rust libraries depend upon crates that do not have a target built for wasm32-wasi, such as the unix crate. The easiest path is to fork those libraries and remove their dependence upon those crates.

WASM / BrightScript limitations

Maximum number of arguments to a function is 32 due to BrightScript
Stack depth is dependent upon BrightScript's limitations and may be less than WASM standards
Floating point math is approximate (where possible we use the correct algorithm, but it may not perfectly match processors)
NaN value bit patterns are not represented
Loading and storing (or reinterpreting) Float/Double (also called f32/f64) to i32/i64 and back may lose precision / bits
Any Float/Double with an exponent of 0 (denormalized) is treated as 0 when loaded
Long jumps and exceptions are not yet supported (header setjmp.h does not exist, but we provide a stub that aborts)
BrightScript files cannot exceed 2MB and must be broken up
- Results in Error loading file. (compile error &hb9) in pkg:/source/test.brs(NaN)
- Files are broken up automatically by wasm2brs via adding a number to the end (e.g. main.brs, main1.brs, main2.brs...)
BrightScript debugger will wrap line numbers beyond 65536 (overflow)
- Files are broken up automatically by wasm2brs so they don't exceed 65536, in the same way as the 2MB limit
For the following BrightScript errors, optimizing (O4 or Oz) helps alleviate the issues:
- BrightScript has an internal limit on the number of If/Else If blocks in a function
  - Results in Internal limit size exceeded. (compile error &hae) in pkg:/source/test.brs(...)
  - By observation, allowed to have maximum 279 blocks for the first group, and then maximum 25 blocks for subsequent groups
  - The last Else clause does not contribute to this limit
  - No limit on how many groups
- BrightScript has an internal limit of 253 variables in a function including function parameters
  - Results in Variable table size exceeded. (compile error &hb0)
- BrightScript has an internal limit of 256 goto labels in a function
  - Results in Label/Line Not Found. (compile error &h0e) in pkg:/source/test.brs(NaN)'label256'
  - A function can actually have more than 256 labels, but any attempts to goto labels beyond 256 will fail with the above error
  - BrightScript compilation becomes exponentially slower with the number of labels in a function (beyond 10000 will hard lock the device)

WASI limitations

Environment variables, command line arguments, and stdout/stderr/stdin strings are always UTF8 encoding

API

Function external_append_stdin(bytesOrString as Dynamic) as Void

Append an roByteArray or String to stdin

Hooks

m.external_print_line = custom_print_line:

Signature: Function custom_print_line(fd as Integer, str as String) as Void
Will be called every time a line is parsed by stdout or stderr.
Will NOT be called if the user provides their own m.external_output, however the helper function PrintAndConsumeLines can emulate the same behavior.

m.external_output = custom_output:

Signature: Function custom_output(fd as Integer, bytes as Object) as Void
Parameter bytes is an roByteArray
Will be called when raw bytes are written to stdout (fd = 1) or stderr (fd = 2).
Useful if the output of a program is binary data instead of text, or if special parsing is needed.
Overriding this function will prevent m.external_print_line from being called, however the helper function PrintAndConsumeLines can emulate the same behavior.

m.external_wait_for_stdin = custom_wait_for_stdin:

Signature: Function custom_wait_for_stdin() as Void
Called when an attempt was made to read from stdin, but there was no bytes available.
During this callback, you should invoke external_append_stdin.
When the callback completes, the program will continue its attempt to read from stdin.

Run tests

Run all the tests, this will auto discover your device with a default password of rokudev.

./run.sh make run_test

To run a specific test you can specify the .wast file as an absolute path, otherwise it assumes it's in the third_part/testsuite/ directory, for example i32.wast:

./run.sh make run_test ARGS="wast i32.wast"

To use a non-default password:

./run.sh make run_test ARGS="password ..."

To deploy to a specific device (e.g. 1.2.3.4):

./run.sh make run_test ARGS="deploy 1.2.3.4"

To provide multiple arguments:

./run.sh make run_test ARGS="password ... deploy 1.2.3.4 wast i32.wast"

MotleyCoderDev/wasm2brs