Universal, cross-language WebAssembly framework for building plug-in systems and polyglot apps

# Extism Go SDK

This repo houses the Go SDK for integrating with the [Extism](https://extism.org/) runtime. Install this library into your host Go applications to run Extism plugins.

Join the [Extism Discord](https://extism.org/discord) and chat with us!

## Installation

Install via `go get`:

```
go get github.com/extism/go-sdk
```

## Reference Docs

You can find the reference docs at [https://pkg.go.dev/github.com/extism/go-sdk](https://pkg.go.dev/github.com/extism/go-sdk).

## Getting Started

This guide should walk you through some of the concepts in Extism and this Go library.

### Creating A Plug-in

The primary concept in Extism is the [plug-in](https://extism.org/docs/concepts/plug-in). You can think of a plug-in as a code module stored in a `.wasm` file.

Plug-in code can come from a file on disk, object storage or any number of places. Since you may not have one handy let's load a demo plug-in from the web. Let's
start by creating a main func and loading an Extism Plug-in:

```go
package main

import (
	"context"
	"fmt"
	"github.com/extism/go-sdk"
	"os"
)

func main() {
	manifest := extism.Manifest{
		Wasm: []extism.Wasm{
			extism.WasmUrl{
				Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
			},
		},
	}

	ctx := context.Background()
	config := extism.PluginConfig{}
	plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

	if err != nil {
		fmt.Printf("Failed to initialize plugin: %v\n", err)
		os.Exit(1)
	}
}
```
> **Note**: See [the Manifest docs](https://pkg.go.dev/github.com/extism/go-sdk#Manifest) as it has a rich schema and a lot of options.

### Calling A Plug-in's Exports

This plug-in was written in Rust and it does one thing, it counts vowels in a string. As such, it exposes one "export" function: `count_vowels`. We can call exports using [extism.Plugin.Call](https://pkg.go.dev/github.com/extism/go-sdk#Plugin.Call).
Let's add that code to our main func:

```go
func main() {
    // ...

	data := []byte("Hello, World!")
	exit, out, err := plugin.Call("count_vowels", data)
	if err != nil {
		fmt.Println(err)
		os.Exit(int(exit))
	}

	response := string(out)
	fmt.Println(response)
    // => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
}
```

Running this should print out the JSON vowel count report:

```bash
$ go run main.go
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
```

All exports have a simple interface of optional bytes in, and optional bytes out. This plug-in happens to take a string and return a JSON encoded string with a report of results.

> **Note**: If you want to pass a custom `context.Context` when calling a plugin function, you can use the [extism.Plugin.CallWithContext](https://pkg.go.dev/github.com/extism/go-sdk#Plugin.CallWithContext) method instead.


### Plug-in State

Plug-ins may be stateful or stateless. Plug-ins can maintain state between calls by the use of variables. Our count vowels plug-in remembers the total number of vowels it's ever counted in the "total" key in the result. You can see this by making subsequent calls to the export:

```go
func main () {
    // ...

    exit, out, err := plugin.Call("count_vowels", []byte("Hello, World!"))
    if err != nil {
        fmt.Println(err)
        os.Exit(int(exit))
    }
    fmt.Println(string(out))
    // => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}

    exit, out, err = plugin.Call("count_vowels", []byte("Hello, World!"))
    if err != nil {
        fmt.Println(err)
        os.Exit(int(exit))
    }
    fmt.Println(string(out))
    // => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}
}

```

These variables will persist until this plug-in is freed or you initialize a new one.

### Configuration

Plug-ins may optionally take a configuration object. This is a static way to configure the plug-in. Our count-vowels plugin takes an optional configuration to change out which characters are considered vowels. Example:

```go
func main() {
    manifest := extism.Manifest{
        Wasm: []extism.Wasm{
            extism.WasmUrl{
                Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
            },
        },
        Config: map[string]string{
            "vowels": "aeiouyAEIOUY",
        },
    }

    ctx := context.Background()
    config := extism.PluginConfig{}

    plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

    if err != nil {
        fmt.Printf("Failed to initialize plugin: %v\n", err)
        os.Exit(1)
    }

    exit, out, err := plugin.Call("count_vowels", []byte("Yellow, World!"))
    if err != nil {
        fmt.Println(err)
        os.Exit(int(exit))
    }

    fmt.Println(string(out))
    // => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}
}
```

### Host Functions

Let's extend our count-vowels example a little bit: Instead of storing the `total` in an ephemeral plug-in var, let's store it in a persistent key-value store!

Wasm can't use our KV store on it's own. This is where [Host Functions](https://extism.org/docs/concepts/host-functions) come in.

[Host functions](https://extism.org/docs/concepts/host-functions) allow us to grant new capabilities to our plug-ins from our application. They are simply some Go functions you write which can be passed down and invoked from any language inside the plug-in.

Let's load the manifest like usual but load up this `count_vowels_kvstore` plug-in:

```go
manifest := extism.Manifest{
    Wasm: []extism.Wasm{
        extism.WasmUrl{
            Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels_kvstore.wasm",
        },
    },
}
```

> *Note*: The source code for this is [here](https://github.com/extism/plugins/blob/main/count_vowels_kvstore/src/lib.rs) and is written in rust, but it could be written in any of our PDK languages.

Unlike our previous plug-in, this plug-in expects you to provide host functions that satisfy our its import interface for a KV store.

We want to expose two functions to our plugin, `kv_write(key string, value []bytes)` which writes a bytes value to a key and `kv_read(key string) []byte` which reads the bytes at the given `key`.
```go
// pretend this is Redis or something :)
kvStore := make(map[string][]byte)

kvRead := extism.NewHostFunctionWithStack(
    "kv_read",
    func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
        key, err := p.ReadString(stack[0])
        if err != nil {
            panic(err)
        }

        value, success := kvStore[key]
        if !success {
            value = []byte{0, 0, 0, 0}
        }

        stack[0], err = p.WriteBytes(value)
    },
    []ValueType{ValueTypePTR},
    []ValueType{ValueTypePTR},
)

kvWrite := extism.NewHostFunctionWithStack(
    "kv_write",
    func(ctx context.Context, p *extism.CurrentPlugin, stack []uint64) {
        key, err := p.ReadString(stack[0])
        if err != nil {
            panic(err)
        }

        value, err := p.ReadBytes(stack[1])
        if err != nil {
            panic(err)
        }

        kvStore[key] = value
    },
    []ValueType{ValueTypePTR, ValueTypePTR},
    []ValueType{},
)
```

> *Note*: In order to write host functions you should get familiar with the methods on the [extism.CurrentPlugin](https://pkg.go.dev/github.com/extism/go-sdk#CurrentPlugin) type. The `p` parameter is an instance of this type.

We need to pass these imports to the plug-in to create them. All imports of a plug-in must be satisfied for it to be initialized:

```go
plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{kvRead, kvWrite});
```

Now we can invoke the event:

```go
exit, out, err := plugin.Call("count_vowels", []byte("Hello, World!"))
// => Read from key=count-vowels"
// => Writing value=3 from key=count-vowels"
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

exit, out, err = plugin.Call("count_vowels", []byte("Hello, World!"))
// => Read from key=count-vowels"
// => Writing value=6 from key=count-vowels"
// => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}
```

### Enabling Compilation Cache
While Wazero (the underlying Wasm runtime) is very fast in initializing modules, you can make subsequent initializations even faster by enabling the compilation cache:

```go
ctx := context.Background()
// you can also use a file system cache: wazero.NewCompilationCacheWithDir(cacheDir)
cache := wazero.NewCompilationCache()

// If the cache is configured, the engine is shared across multiple instances of
// Plugin/CompiledPlugin, and its lifetime is not bound to them. Instead, the engine is alive until Cache.Close is called.
// This means that when using wazero compilation cache with a compiled plugin, the lifetime of the compiled plugin is tied to the cache instance.
// Make sure not to close the cache until you're done with all compiled plugins that depend on it.
defer cache.Close(ctx)

manifest := Manifest{Wasm: []Wasm{WasmFile{Path: "wasm/noop.wasm"}}}

config := PluginConfig{
    EnableWasi:    true,
    ModuleConfig:  wazero.NewModuleConfig(),
    RuntimeConfig: wazero.NewRuntimeConfig().WithCompilationCache(cache),
}

_, err := NewPlugin(ctx, manifest, config, []HostFunction{})
```

### Pre-compiling plugins

If you need to create multiple instances of the same plugin, especially in concurrent scenarios, it's more efficient to first compile the plugin once and then create instances from the `CompiledPlugin`:

```go
manifest := extism.Manifest{
    Wasm: []extism.Wasm{
        extism.WasmUrl{
            Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
        },
    },
}

ctx := context.Background()
config := extism.PluginConfig{}

// Step 1: Compile the plugin once
compiledPlugin, err := extism.NewCompiledPlugin(ctx, manifest, config, []extism.HostFunction{})
if err != nil {
    panic(err)
}

// Example: Using the compiled plugin in multiple goroutines
var wg sync.WaitGroup
for i := 0; i < 3; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        
        // Step 2: Create an instance from the compiled plugin
        plugin, err := compiledPlugin.Instance(ctx, extism.PluginInstanceConfig{})
        if err != nil {
            fmt.Printf("Failed to initialize plugin: %v\n", err)
            return
        }
        defer plugin.Close(ctx)
        
        data := []byte(fmt.Sprintf("Hello, World from goroutine %d!", id))
        _, out, err := plugin.Call("count_vowels", data)
        if err != nil {
            fmt.Println(err)
            return
        }
        
        fmt.Printf("Goroutine %d result: %s\n", id, string(out))
    }(i)
}
wg.Wait()
```

> **Note:** When using wazero compilation cache with a compiled plugin, the lifetime of the compiled plugin is tied to the cache instance. Make sure not to close the cache until you're done with all compiled plugins that depend on it.

> **Important:** Each plugin instance has its own state. In the example above, each instance maintains its own "total" count of vowels, not shared with other instances.

### Integrate with Dylibso Observe SDK
Dylibso provides [observability SDKs](https://github.com/dylibso/observe-sdk) for WebAssembly (Wasm), enabling continuous monitoring of WebAssembly code as it executes within a runtime. It provides developers with the tools necessary to capture and emit telemetry data from Wasm code, including function execution and memory allocation traces, logs, and metrics.

While Observe SDK has adapters for many popular observability platforms, it also ships with an stdout adapter:

```go
ctx := context.Background()

adapter := stdout.NewStdoutAdapter()
adapter.Start(ctx)

manifest := manifest("nested.c.instr.wasm")

config := PluginConfig{
    ModuleConfig:   wazero.NewModuleConfig().WithSysWalltime(),
    EnableWasi:     true,
    ObserveAdapter: adapter.AdapterBase,
}

plugin, err := NewPlugin(ctx, manifest, config, []HostFunction{})
if err != nil {
    panic(err)
}

meta := map[string]string{
    "http.url":         "https://example.com/my-endpoint",
    "http.status_code": "200",
    "http.client_ip":   "192.168.1.0",
}

plugin.TraceCtx.Metadata(meta)

_, _, _ = plugin.Call("_start", []byte("hello world"))
plugin.Close()
```

### Enable filesystem access

WASM plugins can read/write files outside the runtime. To do this we add `AllowedPaths` mapping of "HOST:PLUGIN" to the `extism.Manifest` of our plugin.

```go
package main

import (
	"context"
	"fmt"
	"os"

	extism "github.com/extism/go-sdk"
)

func main() {
	manifest := extism.Manifest{
		AllowedPaths: map[string]string{
			// Here we specifify a host directory data to be linked
			// to the /mnt directory inside the wasm runtime
			"data": "/mnt",
		},
		Wasm: []extism.Wasm{
			extism.WasmFile{
				Path: "fs_plugin.wasm",
			},
		},
	}

	ctx := context.Background()
	config := extism.PluginConfig{
		EnableWasi: true,
	}
	plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})

	if err != nil {
		fmt.Printf("Failed to initialize plugin: %v\n", err)
		os.Exit(1)
	}

	data := []byte("Hello world, this is written from within our wasm plugin.")
	exit, _, err := plugin.Call("write_file", data)
	if err != nil {
		fmt.Println(err)
		os.Exit(int(exit))
	}
}
```

> *Note*: In order for filesystem APIs to work the plugin needs to be compiled with WASI target. Source code for the plugin can be found [here](https://github.com/extism/go-pdk/blob/main/example/fs/main.go) and is written in Go, but it could be written in any of our PDK languages.

## Build example plugins

Since our [example plugins](./plugins/) are also written in Go, for compiling them we use [TinyGo](https://tinygo.org/):

```sh
cd plugins/config
tinygo build -target wasi -o ../wasm/config.wasm main.go
```


Extism Go SDK

Library to use HTML5 Canvas, with all drawing within go code

# go-canvas

go-canvas is a pure **go**+**webassembly** Library for efficiently drawing on a html5 `canvas` element within the browser from go without requiring calls back to JS to utilise canvas drawing functions.

The library provides the following features:
- Abstracts away the initial DOM interactions to setup the canvas.
- Creates the shadow image frame, and graphical Context to draw on it.
- Initializes basic font cache for text using truetype font.
- Sets up and handles `requestAnimationFrame` callback from the browser.

## Concept 
go-canvas takes an alternate approach to the current common methods for using canvas, allowing all drawing primitives to be done totally with go code, without calling JS. 

### standard syscall way
In a standard WASM application for canvas, the go code must create a function that responds to `requestAnimationFrame` callbacks and renders the frame within that call. It interacts with the canvas drawing primitives via the syscall/js functions and context switches.  i.e. 

```go
laserCtx.Call("beginPath")
laserCtx.Call("arc", gs.laserX, gs.laserY, gs.laserSize, 0, math.Pi*2, false)
laserCtx.Call("fill")
laserCtx.Call("closePath")
```

Downsides of this approach (for me at least), are messy JS calls which can't easily be checked at compile time, forcing a full redraw every frame, even if nothing changed on that canvas, or changes being much slower than the requested frame rate. 

### go native way
go-canvas allows all drawing to be done natively using Go by creating an entirely separate image buffer which is drawn to using a 2D drawing library. I'm currently using one from https://github.com/llgcode/draw2d which provides most of the standard canvas primitives  and more. This shadow Image buffer can be updated at whatever rate the developer deems appropriate, which may very well be slower than the browsers animation rate. 

This shadow Image buffer is then copied over to the browser canvas buffer during each `requestAnimationFrame` callback, at whatever rate the browser requests. The handling of the callback and copy is done automatically within the library.

Secondly, this also allows the option of drawing to the image buffer, outside of the `requestAnimationFrame` callback if required. After some testing it appears that it is still best to do the drawing within the `requestAnimationFrame` callback.

go-canvas provides several options to control all this, and take care of the browser/dom interactions
 - User specifies the go render/draw callback method when calling the START function. This callback passes the graphical context to the render routine.
 - Render routine can choose to return whether any drawing took place. If it returns false, then the `requestAnimationFrame` callback does nothing, just returns immediately, saving CPU cycles. (No point to copy buffers and redraw if nothing has changed) This allows the drawing to be adaptive to the rate of data changes. 
 - The 'start' function accepts a maxFPS parameter. The library will automatically throttle the `requestAnimationFrame` callback to only do redraws or image buffer copies to this max rate. Note it MAY be slower depending on the Render time, and the requirements of the browser doing other work. When a tab is hidden, the browser regularly reduces and may even stop call to the animation callback. No critical timing should be done in the render/draw routings. 
 - You may pass 'nil' for the render function. In this case all drawing happens totally under the users control, outside of the library. This may be more useful in future when WASM supports proper threading. Right now however, testing shows it is slower as all work is in the one thread, and you lose the scheduling benefits of the `requestAnimationFrame` call. 

Drawing therefore, is pure **go**. i.e. 

```go
func Render(gc *draw2dimg.GraphicContext) bool {
    // {some movement code removed for clarity, see the demo code for full function}
    // draws red 🔴 laser
    gc.SetFillColor(color.RGBA{0xff, 0x00, 0x00, 0xff})
    gc.SetStrokeColor(color.RGBA{0xff, 0x00, 0x00, 0xff})

    gc.BeginPath()
    gc.ArcTo(gs.laserX, gs.laserY, gs.laserSize, gs.laserSize, 0, math.Pi*2)
    gc.FillStroke()
    gc.Close()
return true  // Yes, we drew something, copy it over to the browser
```
If you do want to render outside the animation loop, a simple way to cause the code to draw the frame on schedule, independent from the browsers callbacks, is to use `time.Tick`. An example is in the demo app below. 

If however your image is only updated from user input or some network activity, then it would be straightforward to fire the redraw only when required from these inputs. This can be controlled within the Render function, by just returning FALSE at the start. Nothing is draw, nor copied (saving CPU time) and the previous frames data remains.

### Known issues !
~~There is currently a likely race condition for long draw functions, where the `requestAnimationFrame` may get a partially completed image buffer. This is more likely the longer the user render operation takes. Currently think how best to handle this, ideally without locks.~~ Turns out this is not an issue, due to the single threaded nature. Eventually if drawing is in a separate thread, this will have to be handled. 


# Demo
A simple demo can be found in: ./demo directory. 
This is a shameless rewrite of the 'Moving red Laser' demo by Martin Olsansky https://medium.freecodecamp.org/webassembly-with-golang-is-fun-b243c0e34f02


Compile with `GOOS=js GOARCH=wasm go build -o main.wasm`

Includes a Caddy configuration file to support WASM, so will serve by just running 'caddy' in the demo directory and opening browser to http://localhost:8080

## Live
Live Demo available at: https://markfarnan.github.io/go-canvas

# Future
This library was written after a weekend of investigation and posted on request for the folks on #webassembly on Gophers Slack. 

I intend to extend it further, time permitting, into fully fledged support package for all things go-canvas-wasm related, using this image frame method. 

Several of the ideas I'm considering are: 
- [ ] Support for layered canvas, at least 3 for 'background', 'action' and 'user interaction'
- [ ] Traps & helper functions for mouse interactions over the canvas
- [ ] Unit tests - soon as I figure out how to do tests for WASM work. 
- [ ] Performance improvements in the image buffer copy - https://github.com/agnivade/shimmer/blob/c073303a81ab9a90b6fc14eb6d90c3a1b930025e/load_image_cb.go#L40 has been suggested as a place to start. 
- [X] Detect if nothing has changed for the frame, and if so, don't even recopy the buffer, saving yet more time. May be useful for layers that change less frequently. 
- [X] Multiple draw / render frames to fix the 'incomplete image' problem. -- Not actually a problem
- [X] Tidy up the close/end frame functionality to properly release resources on page unload and prevent 'browser reload errors' due to missing animation callback function.  
- [X] Update for Go 1.13 and Go Modules
- [ ] Add FPS Calculator metric

Others ? Feedback, suggestions etc. welcome. I can be found on Gophers Slack, #Webassembly channel. 

Mark Farnan, February 2020


go-canvas

Go compiler for small places. Microcontrollers, WebAssembly, and command-line tools. Based on LLVM

# TinyGo - Go compiler for small places

[![Linux](https://github.com/tinygo-org/tinygo/actions/workflows/linux.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/linux.yml) [![macOS](https://github.com/tinygo-org/tinygo/actions/workflows/build-macos.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/build-macos.yml) [![Windows](https://github.com/tinygo-org/tinygo/actions/workflows/windows.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/windows.yml) [![Docker](https://github.com/tinygo-org/tinygo/actions/workflows/docker.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/docker.yml) [![Nix](https://github.com/tinygo-org/tinygo/actions/workflows/nix.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/tinygo/actions/workflows/nix.yml) [![CircleCI](https://circleci.com/gh/tinygo-org/tinygo/tree/dev.svg?style=svg)](https://circleci.com/gh/tinygo-org/tinygo/tree/dev)

TinyGo is a Go compiler intended for use in small places such as microcontrollers, WebAssembly (wasm/wasi), and command-line tools.

It reuses libraries used by the [Go language tools](https://golang.org/pkg/go/) alongside [LLVM](http://llvm.org) to provide an alternative way to compile programs written in the Go programming language.

> [!IMPORTANT]
> You can help TinyGo with a financial contribution using OpenCollective. Please see https://opencollective.com/tinygo for more information. Thank you!

## Embedded

Here is an example program that blinks the built-in LED when run directly on any supported board with onboard LED:

```go
package main

import (
    "machine"
    "time"
)

func main() {
    led := machine.LED
    led.Configure(machine.PinConfig{Mode: machine.PinOutput})
    for {
        led.Low()
        time.Sleep(time.Millisecond * 1000)

        led.High()
        time.Sleep(time.Millisecond * 1000)
    }
}
```

The above program can be compiled and run without modification on an Arduino Uno, an Adafruit ItsyBitsy M0, or any of the supported boards that have a built-in LED, just by setting the correct TinyGo compiler target. For example, this compiles and flashes an Arduino Uno:

```shell
tinygo flash -target arduino examples/blinky1
```

## WebAssembly

TinyGo is very useful for compiling programs both for use in browsers (WASM) as well as for use on servers and other edge devices (WASI).

TinyGo programs can run in [Fastly Compute](https://www.fastly.com/documentation/guides/compute/go/), [Fermyon Spin](https://developer.fermyon.com/spin/go-components), [wazero](https://wazero.io/languages/tinygo/) and many other WebAssembly runtimes.

Here is a small TinyGo program for use by a WASI host application:

```go
package main

//go:wasmexport add
func add(x, y uint32) uint32 {
	return x + y
}
```

This compiles the above TinyGo program for use on any WASI Preview 1 runtime:

```shell
tinygo build -buildmode=c-shared -o add.wasm -target=wasip1 add.go
```

You can also use the same syntax as Go 1.24+:

```shell
GOOS=wasip1 GOARCH=wasm tinygo build -buildmode=c-shared -o add.wasm add.go
```

## Installation

See the [getting started instructions](https://tinygo.org/getting-started/) for information on how to install TinyGo, as well as how to run the TinyGo compiler using our Docker container.

## Supported targets

### Embedded

You can compile TinyGo programs for over 94 different microcontroller boards.

For more information, please see https://tinygo.org/docs/reference/microcontrollers/

### WebAssembly

TinyGo programs can be compiled for both WASM and WASI targets.

For more information, see https://tinygo.org/docs/guides/webassembly/

### Operating Systems

You can also compile programs for Linux, macOS, and Windows targets.

For more information:

- Linux https://tinygo.org/docs/guides/linux/

- macOS https://tinygo.org/docs/guides/macos/

- Windows https://tinygo.org/docs/guides/windows/

## Currently supported features:

For a description of currently supported Go language features, please see [https://tinygo.org/lang-support/](https://tinygo.org/lang-support/).

## Documentation

Documentation is located on our web site at [https://tinygo.org/](https://tinygo.org/).

You can find the web site code at [https://github.com/tinygo-org/tinygo-site](https://github.com/tinygo-org/tinygo-site).

## Getting help

If you're looking for a more interactive way to discuss TinyGo usage or
development, we have a [#TinyGo channel](https://gophers.slack.com/messages/CDJD3SUP6/)
on the [Gophers Slack](https://gophers.slack.com).

If you need an invitation for the Gophers Slack, you can generate one here which
should arrive fairly quickly (under 1 min): https://invite.slack.golangbridge.org

## Contributing

Your contributions are welcome!

Please take a look at our [Contributing](https://tinygo.org/docs/guides/contributing/) page on our web site for details.

## Project Scope

Goals:

* Have very small binary sizes. Don't pay for what you don't use.
* Support for most common microcontroller boards.
* Be usable on the web using WebAssembly.
* Good CGo support, with no more overhead than a regular function call.
* Support most standard library packages and compile most Go code without modification.

Non-goals:

* Be efficient while using zillions of goroutines. However, good goroutine support is certainly a goal.
* Be as fast as `gc`. However, LLVM will probably be better at optimizing certain things so TinyGo might actually turn out to be faster for number crunching.
* Be able to compile every Go program out there.

## Why this project exists

> We never expected Go to be an embedded language, and so it’s got serious problems...

-- Rob Pike, [GopherCon 2014 Opening Keynote](https://www.youtube.com/watch?v=VoS7DsT1rdM&feature=youtu.be&t=2799)

TinyGo is a project to bring Go to microcontrollers and small systems with a single processor core. It is similar to [emgo](https://github.com/ziutek/emgo) but a major difference is that we want to keep the Go memory model (which implies garbage collection of some sort). Another difference is that TinyGo uses LLVM internally instead of emitting C, which hopefully leads to smaller and more efficient code and certainly leads to more flexibility.

The original reasoning was: if [Python](https://micropython.org/) can run on microcontrollers, then certainly [Go](https://golang.org/) should be able to run on even lower level micros.

## License

This project is licensed under the BSD 3-clause license, just like the [Go project](https://golang.org/LICENSE) itself.

Some code has been copied from the LLVM project and is therefore licensed under [a variant of the Apache 2.0 license](http://releases.llvm.org/11.0.0/LICENSE.TXT). This has been clearly indicated in the header of these files.

Some code has been copied and/or ported from Paul Stoffregen's Teensy libraries and is therefore licensed under PJRC's license. This has been clearly indicated in the header of these files.


tinygo

# wasmbrowsertest [![Build Status](https://github.com/agnivade/wasmbrowsertest/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/agnivade/wasmbrowsertest/actions/workflows/ci.yml)

Run Go wasm tests easily in your browser.

If you have a codebase targeting the wasm platform, chances are you would want to test your code in a browser. Currently, that process is a bit cumbersome:
- The test needs to be compiled to a wasm file.
- Then loaded into an HTML file along with the wasm_exec.js.
- And finally, this needs to be served with a static file server and then loaded in the browser.

This tool automates all of that. So you just have to type `GOOS=js GOARCH=wasm go test`, and it automatically executes the tests inside a browser !

## Quickstart

- `go install github.com/agnivade/wasmbrowsertest@latest`. This will place the binary in $GOPATH/bin, or $GOBIN, if that has a different value.
- Rename the binary to `go_js_wasm_exec`.
- Add $GOBIN to $PATH if it is not already done.
- Run tests as usual: `GOOS=js GOARCH=wasm go test`.
- You can also take a cpu profile. Set the `-cpuprofile` flag for that.

## Ok, but how does the magic work ?

`go test` allows invocation of a different binary to run a test. `go help test` has a line: 

```
-exec xprog
	    Run the test binary using xprog. The behavior is the same as
	    in 'go run'. See 'go help run' for details.
```

And `go help run` says:

```
By default, 'go run' runs the compiled binary directly: 'a.out arguments...'.
If the -exec flag is given, 'go run' invokes the binary using xprog:
	'xprog a.out arguments...'.
If the -exec flag is not given, GOOS or GOARCH is different from the system
default, and a program named go_$GOOS_$GOARCH_exec can be found
on the current search path, 'go run' invokes the binary using that program,
for example 'go_nacl_386_exec a.out arguments...'. This allows execution of
cross-compiled programs when a simulator or other execution method is
available.
```

So essentially, there are 2 ways:
- Either have a binary with the name of `go_js_wasm_exec` in your $PATH.
- Or set the `-exec` flag in your tests.

Use whatever works for you.

### How is a CPU profile taken ?

A CPU profile is run during the duration of the test, and then converted to the pprof format so that it can be natively analyzed with the Go toolchain.

### Can I run something which is not a test ?

Yep. `GOOS=js GOARCH=wasm go run main.go` also works. If you want to actually see the application running in the browser, set the `WASM_HEADLESS` variable to `off` like so `WASM_HEADLESS=off GOOS=js GOARCH=wasm go run main.go`.

### Can I use this inside Travis ?

Sure.

Add these lines to your `.travis.yml`

```
addons:
  chrome: stable

install:
- go install github.com/agnivade/wasmbrowsertest@latest
- mv $GOPATH/bin/wasmbrowsertest $GOPATH/bin/go_js_wasm_exec
- export PATH=$GOPATH/bin:$PATH
```

Now, just setting `GOOS=js GOARCH=wasm` will run your tests using `wasmbrowsertest`. For other CI environments, you have to do something similar.

### Can I use this inside Github Action?

Sure.

Add these lines to your `.github/workflows/ci.yml`

PS: adjust the go version you need in go-version section

```
on: [push, pull_request]
name: Unit Test
jobs:
  test:
    strategy:
      matrix:
        go-version: [1.xx.x]
        os: [ubuntu-latest]
    runs-on: ${{ matrix.os }}
    steps:
    - name: Install Go
      uses: actions/setup-go@v2
      with:
        go-version: ${{ matrix.go-version }}
    - name: Install chrome
      uses: browser-actions/setup-chrome@latest
    - name: Install dep
      run: go install github.com/agnivade/wasmbrowsertest@latest
    - name: Setup wasmexec
      run: mv $(go env GOPATH)/bin/wasmbrowsertest $(go env GOPATH)/bin/go_js_wasm_exec
    - name: Checkout code
      uses: actions/checkout@v2
```

### What sorts of browsers are supported ?

This tool uses the [ChromeDP](https://chromedevtools.github.io/devtools-protocol/) protocol to run the tests inside a Chrome browser. So Chrome or any blink-based browser will work.

### Why not firefox ?

Great question. The initial idea was to use a Selenium API and drive any browser to run the tests. But unfortunately, geckodriver does not support the ability to capture console logs - https://github.com/mozilla/geckodriver/issues/284. Hence, the shift to use the ChromeDP protocol circumvents the need to have any external driver binary and just have a browser installed in the machine.

### A tip on coverage data using go 1.20 or later:

Code coverage changes introduced in go 1.20 produce multiple 
[coverage data files](https://go.dev/testing/coverage/#working) in binary format.

In wasmbrowsertest, file system operations for coverage files occur via HTTP API calls.
  
Prefer using `-test.gocoverdir=/path/to/coverage` instead of `-test.coverprofile=coverage.out` 
when coverage data is needed. This will prevent http api calls that would read all the coverage data 
files and write the larger `coverage.out` file. 

In a subsequent step, use `go tool covdata -i /path/to/coverage -o coverage.out` or similar to process coverage 
data files into the desired output format. An additional benefit is that multiple test coverage runs that write 
their data to the same coverage directory can be merged together with this command.

## Errors

### `total length of command line and environment variables exceeds limit`

If the error `total length of command line and environment variables exceeds limit` appears, then
the current environment variables' total size has exceeded the maximum when executing Go Wasm binaries.

To resolve this issue, install `cleanenv` and use it to prefix your command.

For example, if these commands are used:
```bash
export GOOS=js GOARCH=wasm
go test -cover ./...
```
The new commands should be the following:
```bash
go install github.com/agnivade/wasmbrowsertest/cmd/cleanenv@latest

export GOOS=js GOARCH=wasm
cleanenv -remove-prefix GITHUB_ -- go test -cover ./...
```

The `cleanenv` command above removes all environment variables prefixed with `GITHUB_` before running the command after the `--`.
The `-remove-prefix` flag can be repeated multiple times to remove even more environment variables.


wasmbrowsertest

# Go DOM binding (and more) for WebAssembly

This library provides a Go API for different Web APIs for WebAssembly target.

It's in an active development, but an API will be carefully versioned to
avoid breaking users.
Use Go dependency management tools to lock a specific version.

More information about Go's WebAssembly support can be found on [Go's WebAssembly wiki page](https://github.com/golang/go/wiki/WebAssembly).

**Features:**

- Better JS API (wrappers for `syscall/js`)
- Basic DOM manipulation, styles, events
- Input elements
- SVG elements and transforms
- `LocalStorage` and `SessionStorage`
- Extension APIs (tested on Chrome):
    - Native Messaging
    - Bookmarks
    - Tabs
- `net`-like library for WebSockets
    - Tested with gRPC
- `wasm-server` for fast prototyping

## Quickstart

Pull the library and install `wasm-server` (optional):

```
go get -u github.com/dennwc/dom
go install github.com/dennwc/dom/cmd/wasm-server
```

Run an example app:

```
cd $GOPATH/src/github.com/dennwc/dom
wasm-server
```

Check result: http://localhost:8080/

The source code is recompiled on each page refresh, so feel free to experiment!

# Similar Projects

- [go-js-dom](https://github.com/dominikh/go-js-dom)

# Editor Configuration

If you are using Visual Studio Code, you can use [workspace settings](https://code.visualstudio.com/docs/getstarted/settings#_creating-user-and-workspace-settings) to configure the environment variables for the go tools.

Your settings.json file should look something like this:

```
{
    "go.toolsEnvVars": { "GOARCH": "wasm", "GOOS": "js" }
}
```


# vert
[![Go Reference](https://pkg.go.dev/badge/github.com/norunners/vert.svg)](https://pkg.go.dev/github.com/norunners/vert)
[![Test](https://github.com/norunners/vert/actions/workflows/test.yml/badge.svg)](https://github.com/norunners/vert/actions/workflows/test.yml)

Package `vert` provides WebAssembly interop between Go and JS values.

## Install
```bash
GOOS=js GOARCH=wasm go get github.com/norunners/vert
```

## Examples
### Hello World!
Below is a trivial string value interop.
```go
package main

import "github.com/norunners/vert"

func main() {
	v := vert.ValueOf("Hello World!")
	// Use v as a JS value.

	s := ""
	v.AssignTo(&s)
	// Use s as a Go value.
}
```

### Structs & Objects
Go structs and JS objects interop seamlessly.
```go
package main

import "github.com/norunners/vert"

type Data struct {
	Message string
}

func main() {
	v := vert.ValueOf(Data{
		Message: "Hello World!",
	})
	// e.g. {"Message": "Hello World!"}

	d := &Data{}
	v.AssignTo(d)
}
```

### Tagged Struct Fields
Tagged struct fields allow defined JS field names.
```go
package main

import "github.com/norunners/vert"

type Data struct {
	Message string `js:"msg"`
}

func main() {
	v := vert.ValueOf(Data{
		Message: "Hello World!",
	})
	// The defined JS tag names the field.
	// e.g. {"msg": "Hello World!"}

	d := &Data{}
	v.AssignTo(d)
}
```

## Error Handling
`AssignTo` returns an `error` value.  
```go
package main

import "github.com/norunners/vert"

type Data struct {
	Message string
}

func main() {
	v := vert.ValueOf("Hello World!")

	d := &Data{}
	if err := v.AssignTo(d); err != nil {
		// Handle error.
	}
}
```

## Why?
Package `syscall/js`, of the Go standard library, has limited interop support between Go and JS values.
1. The function `js.ValueOf` will not accept struct types. The result panics with `ValueOf: invalid value`.
2. The type `js.Value.` does not support an `Interface` or *assignment* method for non-basic Go values.
However, the methods `Bool`, `Int`, `Float` and `String` support basic Go values.

Package `vert` leverages and extends `syscall/js` to accommodate these shortcomings.

## License
* [MIT License](LICENSE)


vert

Bindings for DOM and HTML generated from WebIDL

# WebAPI

Go Language Web Assembly bindings for DOM, HTML etc

[![GoDoc](https://godoc.org/github.com/gowebapi/webapi?status.svg)](https://godoc.org/github.com/gowebapi/webapi)

> __WARNING__: The current API is in very early state and should be consider to be expremental. There is upcommig changed like moving types into multiple packages.

This library is trying to be feature complete and up to date with current standard to let everything a browser having to offect be available in WebAssembly in a Go API accessable. To achive this most
of the code is [generated](https://github.com/gowebapi/webidlgenerator) from [WebIDL files](https://github.com/gowebapi/idl). WebIDL files can be found in different standard making it easiser to be up to date than handwritten binding code.

Example:

```golang
func main() {
    element := webapiall.GetWindow().Document().GetElementById("foo")
    // NOTE: After Go 1.12, the extra call to JSValue() will no loger   be needed
    button := webapiall.HTMLButtonElementFromJS(element.JSValue())
    button.SetValue("Hello World")
}
```

## Roadmap

|Milestone|Status|Description|
|----|----|----|
|1|Ongoing|Be abto to read and and understand all of WebIDL syntax. Notible missing thing are _namespace_ and _union_|
|2|Planned|Easy up the syntax. Promise will be refactor and other places where simplifications can be done. Classes can be renamed like clipboard.ClipboardPermission to clipboard.Permission.|
|3|Planned|API Stability with a predefined release schedule. Documentation and added examples|

More infomation of missing stuff can be found on the [generator status info](https://github.com/gowebapi/webidlgenerator).


The Best Go Libraries For WebAssembly (7)

Extism Go SDK

go-canvas

tinygo

wasmbrowsertest

dom

vert

webapi