Nelua support

[christopher-kleine]

Nelua can compile to WebAssembly using Emscripten. An example can be found here: https://github.com/edubart/nelua-game2048

• w4 new: Add new project template
• w4 watch: Add new filename suffix + build/run support
• w4 png2src: Add new language parameter
• Website: Setup documentation
• Website: Translated code snippets for all guide pages
• Website: Add code to Snake tutorial

[Andre-LA]

I'm investigating this at my free time, I'll give an update (maybe on discord instead) once I got some progress.

[aduros]

I made some progress with this and have a minimal cart compiling and running:

build.sh:

#!/bin/sh -e

CFLAGS="-mexec-model=reactor -Wl,--allow-undefined,-zstack-size=1024,--no-entry,--import-memory,--initial-memory=65536,--max-memory=65536,--global-base=6560,--export-dynamic"

./nelua \
    --cc "$WASI_SDK_PATH/bin/clang --sysroot=$WASI_SDK_PATH/share/wasi-sysroot" \
    --cflags="$CFLAGS" --verbose -Pabort="'trap'" \
    ./wasm4-test.nelua -o out.wasm --release

wasm4-test.nelua:

-- Pointer to WASM-4 memory register
local DRAW_COLORS = (@*uint16)(0x14);

-- Import some WASM-4 functions
local function text (str: cstring <const>, x: int32, y: int32): void <cimport> end
local function trace (str: cstring <const>): void <cimport> end

-- Hack to call Nelua initialization
local function nelua_main (argc: integer, argv: integer): void <cimport, nodecl> end
local function _start (): void <cexport, codename "_start">
    nelua_main(0, 0)
end

local x = 69

local function update (): void <cexport, codename "update">
    -- $ is used to deref a pointer
    $DRAW_COLORS = 0x23

    -- Call an imported function
    text("Hello from Nelua!", x, 20)
    x = (x + 1) % 160

    trace("Trace works")
end

trace("Hello from initializer")

Some possible next steps:

• Create a wasm4.nelua with all the bindings
• Nelua lets you add compiler configuration in source files like this: https://github.com/edubart/nelua-game2048/blob/master/config.nelua. I think we should be able to move all the clang flags into the top of wasm4.nelua so we don't need a build.sh?
• I haven't tested GC or memory allocation at all yet
• Non-release builds currently don't work because Nelua calls stdio functions in its panic handler

[ghost]

• Website: Tell the user not to download wasi-sdk in a folder containing white space in the path name

For example:
C:\Program Files\wasi-sdk-14.0 won't work because there's a white space between Program and Files

The CC should've been C:\Program Files\wasi-sdk-14.0\bin\clang, but instead the nelua compiler will use C:\Program and ignore the remaining i.e. Files\wasi-sdk-14.0\bin\clang

[aduros]

Thanks for flagging about spaces in the compiler path, that should be fixed now. It was actually affecting our C/C++ template too, it's been fixed there as well.

[edubart]

@aduros To fix the issue that made debug builds fail, I've recently made changes in the Nelua compiler to allow the user to setup a custom error writer, so then calls to fwrite, fputs, fflush won't be generated.

There is the new pragma writestderr:

  --[[
  Changes how messages are written to stderr when a runtime error occur (panic, assert, check, etc).
  This pragma can be one of the following values:
  * `'none'`: the application with call system's `exit(-1)`
  * `'hooked'`: will call error message handler defined by the application, then you must define
  `function nelua_write_stderr(msg: cstring, len: usize, flush: boolean): void`
  * `'stdout'`: messages will be printed to stdout
  * `'stderr': messages will be printed to stderr (this is the default)
  ]]
  writestderr = shaper.one_of{'none', 'hooked', 'stdout', 'stderr'}:is_optional(),

You could use it with the command line `-Pwritestderr="'none'" to ignore error messages, but it's ideal to print them, so I suggest adding this to the template:

require 'stringbuilder' -- for print()

global function trace(str: cstring <const>): void <cimport> end

-- Make abort generate an invalid instruction instead of calling C `abort()`.
## context.rootpragmas.abort = 'trap'

-- Hook runtime errors to write using `trace()` instead of writing to C `stderr`.
## context.rootpragmas.writestderr = 'hooked'
local function write_stderr(msg: cstring, len: usize, flush: boolean): void <codename'nelua_write_stderr'>
  trace(msg)
end

-- Replace global print function to write using `trace()` instead of writing to C `stdout`.
global function print(...: varargs)
  local sb: stringbuilder <close>
  ## for i=1,select('#', ...) do
    ## if i > 1 then
      sb:write('\t')
    ## end
    sb:write(#[select(i, ...)]#)
  ## end
  trace(sb:view())
end

Notice that I've already set the necessary pragmas in the above code, if you do the same way you can remove the -P command line flags.

I've also overridden print to use trace because many Lua users like it to do "print" debugging, and the original print still writes to C stdout, so it would trigger a compile error if not overriden.