# Web Assembly

> Based on <small>❤️</small> [wasmoon](https://github.com/ceifa/wasmoon)

The [`lrocket-build-wasm`](https://codeberg.org/leso-kn/lrocket-build-wasm) compiler extension adds three WebAssembly build targets to lrc: `.html`, `.js` and `.wasm`.

It is based on the [wasmoon](https://github.com/ceifa/wasmoon) project and works by loading base64-encoded versions of custom-tailored Lua binaries. This allows to embed compiled Lua bundles and **native Lua modules** (e.g. written in C) via WebAssembly.

The result is a single Javascript file which runs Lua code that can interact with the DOM / Javascript APIs and vice versa – meaning that other `<script>`-tags can interact with variables and functions provided by Lua (see [Interacting with Javascript APIs](#interacting-with-javascript-apis)).

## Requirements

* Make sure to have the [WASI SDK](https://github.com/WebAssembly/wasi-sdk/releases) and a compatible compiler (e.g. [`clang`](https://clang.llvm.org/)) installed

## Compiling for Web Browsers

### Usage with LuaRocks <span style="float: right; color: #2a2; font-size: .7em">[ Recommended ]</span>

To use the extension via the [LuaRocks](https://luarocks.org/) package manager, simply create a [rockspec-file](https://github.com/luarocks/luarocks/blob/main/docs/luarocks_write_rockspec.md) with the following contents:

> **Note** The [LRocket LuaRocks Integration](luarocks-integration) will automatically install the [`lrocket-build-wasm`](https://luarocks.org/modules/leso-kn/lrocket-build-wasm) package when the `otype` is set to `wasm[-...]` in your rockspec. LuaRocks `v3.11.0+` will even install the LRocket integration automatically when the build `type` is set to `lrocket`.

```lua
-- lua-example-website-scm-0.rockspec
...

build = {
	type = 'lrocket',
	otype = 'wasm-html'  -- or 'wasm-js' or 'wasm'
	entrypoint = 'main.lua'
	output = 'main.html'
}
```

### Command-Line Usage

The extension provides three targets for WebAssembly:

#### Javascript

You can compile to Javascript, to include your Lua code as Javascript module:

```bash
> lrc --otype wasm-js main.lua -o output-lib.js
```

#### HTML

You can compile directly to HTML, to write your complete page in Lua (starting off with `document.body.innerHTML = [[...]]`):

```bash
> lrc --otype wasm-html main.lua -o index.html
```

#### WASM

Or compile to `.wasm` to handle the embedding into the libwasmoon template yourself:

```bash
> lrc --otype wasm main.lua -o lua-module.wasm
```

If you would like to handle the compilation yourself (e.g. use a different compiler than lrc) virtually any compiler that targets wasm32 can be used to build your own Lua binary script.

For details see [Using a Different Compiler](#using-a-different-compiler).

## Interacting with Javascript APIs

Libwasmoon makes the [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window)-object available inside the global Lua environment – This allows to use any desired Javascript API via Lua syntax!

All is made possible by the fantastic work of the [wasmoon](https://github.com/ceifa/wasmoon) project!

### Examples

**Button Callback**

```lua
document.innerHTML = '<button>Click me!</button>'

local button = document.querySelector 'button'
button.addEventListener('click', function()
    alert('Lua function called!')
end)
```

**Lua Function in Javascript**

> **Tip** [`self`](https://developer.mozilla.org/en-US/docs/Web/API/Window/self) is an alias for the [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object and since Javascript compiled with lrc works in [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) too, it is good practice to use [`self`](https://developer.mozilla.org/en-US/docs/Web/API/Window/self) as it works in both regular and Service Worker contexts:

To export a function to the global Javascript environment you can add it to the [`self`](https://developer.mozilla.org/en-US/docs/Web/API/Window/self) object:

```lua
-- better: self.myLuaFunction()
function window.myLuaFunction()
    return math.random(1, 42)
end
```

```javascript
// in javascript
alert('The answer to everything is: ' + myLuaFunction());
```

**Geo Location**

```lua
navigator.geolocation.getCurrentPosition(function(loc)
    -- prints to console.log()
    print('You are here', loc.coords.latitude, loc.coords.longitude)
end)
```

## Advanced Use

### Using a Different Compiler

Any compiler that targets wasm32 (ideally `wasm32-wasip1` / `wasm32-wasip1-threads`) can be used to build the binary that will be embedded into the libwasmoon template.

The compiled binary should export a symbol named `void __lr_entrypoint(lua_State *L)` (called by libwasmoon after the Lua-state has been initialized).

We recommend linking against [lua-wasm32](https://codeberg.org/leso-kn/lua-wasm32), which is a static lua library (the one lrc links against when compiling bundles for WebAssembly). It is available via luarocks (note that the rock also ships a copy of the libwasmoon template):

```bash
> luarocks install lua-wasm32
```

For example, the [clang](https://clang.llvm.org/)-compiler could be used to compile a custom lua interpreter which can then be embedded into the libwasmoon template:

```bash
> clang --target=wasm32-wasip1-threads -o lua-module.wasm my-custom-interpreter.c \
    <path-to-lua-wasm32>/lib/liblua-5.4.a
```

Turining `lua-module.wasm` into Javascript:

```bash
> sed dist/loader.js.tpl "s/{{libwasmoon:wasm_bytes}}/$(base64 -w0 lua-module.wasm)/g" > \
    output-lib.js
```

Using the module in HTML:

```html
<!DOCTYPE html>
<body></body>
<script src="output-lib.js"></script>
```

You may also embed the script between an inline `<script>...</script>`-tag.