Google Git
Sign in
go / wiki / ff596d59bb7d45b52c0cb02767ba0a233c388d9b / . / WebAssembly.asciidoc
blob: e8cf2577d87c44cf094ff7e2ff752e086ed20694 [file] [log] [blame]
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]1WebAssembly
2===========
3:toc:
4:toc-title:
5:toclevels: 2
6:icons:
7
8
9# Introduction
10
Justin Cliftff596d52019-04-03 17:41:23 +1100[diff] [blame^]11Go 1.11 added an experimental port to WebAssembly. Go 1.12 has
12improved some parts of it, with further improvements expected in Go
131.13.
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]14
15WebAssembly is described on its https://webassembly.org[home page] as:
16
17> WebAssembly (abbreviated _Wasm_) is a binary instruction format for
18> a stack-based virtual machine. Wasm is designed as a portable
19> target for compilation of high-level languages like C/C++/Rust,
20> enabling deployment on the web for client and server applications.
21
22**********************************************************************
Justin Cliftb6813da2018-10-26 12:02:47 +1100[diff] [blame]23If you're new to WebAssembly read the <<Getting Started>> section,
Justin Clift03e0fb22018-10-26 12:04:38 +1100[diff] [blame]24watch some of the https://github.com/golang/go/wiki/WebAssembly#go-webassembly-talks[Go Webassembly talks],
25then take a look at the <<Further examples>> below.
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]26**********************************************************************
27
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]28
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]29# Getting Started
30
31This page assumes a functional Go 1.11 or newer installation. For
32troubleshooting, see the https://github.com/golang/go/wiki/InstallTroubleshooting[Install Troubleshooting]
33page.
34
35To compile a basic Go package for the web:
36
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]37```go
38package main
39
40import "fmt"
41
42func main() {
43 fmt.Println("Hello, WebAssembly!")
44}
45```
46
47Set `GOOS=js` and `GOARCH=wasm` environment variables to compile
48for WebAssembly:
49
50```sh
51$ GOOS=js GOARCH=wasm go build -o main.wasm
52```
53
54That will build the package and produce an executable WebAssembly
55module file named main.wasm. The .wasm file extension will make it
56easier to serve it over HTTP with the correct Content-Type header
57later on.
58
59To execute main.wasm in a browser, we'll also need a JavaScript
60support file, and a HTML page to connect everything together.
61
62Copy the JavaScript support file:
63
64```sh
65$ cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" .
66```
67
68Create an `index.html` file:
69
70```HTML
71<html>
72 <head>
73 <meta charset="utf-8">
74 <script src="wasm_exec.js"></script>
75 <script>
76 const go = new Go();
77 WebAssembly.instantiateStreaming(fetch("main.wasm"), go.importObject).then((result) => {
78 go.run(result.instance);
79 });
80 </script>
81 </head>
82 <body></body>
83</html>
84```
85
86If your browser doesn't yet support `WebAssembly.instantiateStreaming`,
87you can use a https://github.com/golang/go/blob/b2fcfc1a50fbd46556f7075f7f1fbf600b5c9e5d/misc/wasm/wasm_exec.html#L17-L22[polyfill].
88
89Then serve the three files (`index.html`, `wasm_exec.js`, and
90`main.wasm`) from a web server. For example, with
91https://github.com/shurcooL/goexec#goexec[`goexec`]:
92
93```sh
94$ goexec 'http.ListenAndServe(":8080", http.FileServer(http.Dir(".")))'
95```
96
97Or use your own https://play.golang.org/p/pZ1f5pICVbV[basic HTTP server command].
98
99Finally, navigate to http://localhost:8080/index.html, open the
100JavaScript debug console, and you should see the output. You can
101modify the program, rebuild `main.wasm`, and refresh to see new
102output.
103
Justin Cliftff596d52019-04-03 17:41:23 +1100[diff] [blame^]104# Go WebAssembly UI framework(s)
105
106An experimental new framework https://github.com/vugu/vugu[Vugu] is
107worth trying out, if you're looking for something like VueJS. :smile:
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]108
109# Executing WebAssembly with Node.js
110
111It's possible to execute compiled WebAssembly modules using Node.js
112rather than a browser, which can be useful for testing and automation.
113
114With Node installed and in your `PATH`, set the `-exec` flag to the
115location of `go_js_wasm_exec` when you execute `go run` or `go test`.
116
117By default, `go_js_wasm_exec` is in the `misc/wasm` directory of your
118Go installation.
119
120```
121$ GOOS=js GOARCH=wasm go run -exec="$(go env GOROOT)/misc/wasm/go_js_wasm_exec" .
122Hello, WebAssembly!
123$ GOOS=js GOARCH=wasm go test -exec="$(go env GOROOT)/misc/wasm/go_js_wasm_exec"
124PASS
125ok example.org/my/pkg 0.800s
126```
127
128Adding `go_js_wasm_exec` to your `PATH` will allow `go run` and `go test` to work for `js/wasm` without having to manually provide the `-exec` flag each time:
129
130```
131$ export PATH="$PATH:$(go env GOROOT)/misc/wasm"
132$ GOOS=js GOARCH=wasm go run .
133Hello, WebAssembly!
134$ GOOS=js GOARCH=wasm go test
135PASS
136ok example.org/my/pkg 0.800s
137```
138
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]139
140# Go WebAssembly talks
141
Justin Cliftbda80042018-11-28 15:47:34 +1100[diff] [blame]142* https://www.youtube.com/watch?v=4kBvvk2Bzis[Building a Calculator with Go and WebAssembly] (https://tutorialedge.net/golang/go-webassembly-tutorial/[Source code])
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]143* https://www.youtube.com/watch?v=iTrx0BbUXI4[Get Going with WebAssembly]
144
145
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]146# Interacting with the DOM
147
148See https://godoc.org/syscall/js.
149
150Alternatively, https://github.com/dennwc/dom[a library for streamlining DOM manipulation]
151is in development.
152
martin-juhlinb16e04c2019-02-21 08:11:30 +0100[diff] [blame]153There is also a https://gowebapi.github.io/[binding generator] that can be used.
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]154
Justin Cliftff596d52019-04-03 17:41:23 +1100[diff] [blame^]155
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]156# Editor configuration
157
Justin Cliftfb2e83b2019-01-24 02:27:49 +1100[diff] [blame]158* https://github.com/golang/go/wiki/Configuring-GoLand-for-WebAssembly[Configuring GoLand and Intellij Ultimate for WebAssembly] - Shows the exact steps needed for getting Wasm working in GoLand and Intellij Ultimate
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]159
160
161# WebAssembly in Chrome
162
163If you run a newer version of Chrome there is a flag (`chrome://flags/#enable-webassembly-baseline`) to enable Liftoff, their new compiler, which should significantly improve load times. Further info https://chinagdg.org/2018/08/liftoff-a-new-baseline-compiler-for-webassembly-in-v8/[here].
164
165
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]166# Debugging
167
168WebAssembly doesn't *yet* have any support for debuggers, so you'll
169need to use the good 'ol `println()` approach for now to display
170output on the JavaScript console.
171
172An official https://github.com/WebAssembly/debugging[WebAssembly Debugging Subgroup]
173has been created to address this, with some initial investigation and
174proposals under way:
175
176* https://fitzgen.github.io/wasm-debugging-capabilities/[WebAssembly Debugging Capabilities Living Standard]
177 (https://github.com/fitzgen/wasm-debugging-capabilities[source code for the doc])
178* https://yurydelendik.github.io/webassembly-dwarf/[DWARF for WebAssembly Target]
179 (https://github.com/yurydelendik/webassembly-dwarf/[source code for the doc])
180
181Please get involved and help drive this if you're interested in the Debugger side of things. :smile:
182
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]183
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]184# Known bug(s)
185
Justin Cliftb910f042018-11-09 11:50:27 +1100[diff] [blame]186Go releases prior to 1.11.2 https://github.com/golang/go/issues/27961[have a bug] which can generate incorrect wasm code in some (rare) circumstances.
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]187
188If your Go code compiles to wasm without problem, but produces an error like this when run in the browser:
189
190```
191CompileError: wasm validation error: at offset 1269295: type mismatch: expression has type i64 but expected f64
192```
193
194Then you're probably hitting this error.
195
Justin Cliftb910f042018-11-09 11:50:27 +1100[diff] [blame]196The solution is to upgrade to Go 1.11.2 or later.
Justin Cliftbb1ad3d2018-10-26 02:35:20 +1100[diff] [blame]197
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]198
199# Further examples
200
201## General
202* https://github.com/agnivade/shimmer[Shimmer] - Image transformation in wasm using Go
203
204## Canvas (2D)
205* https://github.com/stdiopt/gowasm-experiments[GoWasm Experiments] - Demonstrates
206 working code for several common call types
207** https://stdiopt.github.io/gowasm-experiments/bouncy[bouncy]
208** https://stdiopt.github.io/gowasm-experiments/rainbow-mouse[rainbow-mouse]
209** https://stdiopt.github.io/gowasm-experiments/repulsion[repulsion]
Justin Clift41abc962018-10-26 00:25:04 +1100[diff] [blame]210** https://stdiopt.github.io/gowasm-experiments/bumpy[bumpy] - Uses the 2d canvas, and a 2d physics engine. Click around on the screen to create objects then watch as gravity takes hold!
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]211** https://stdiopt.github.io/gowasm-experiments/arty/client[arty]
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]212* https://github.com/djhworld/gomeboycolor-wasm[Gomeboycolor-wasm]
213** WASM port of an experimental Gameboy Color emulator. The https://djhworld.github.io/post/2018/09/21/i-ported-my-gameboy-color-emulator-to-webassembly/[matching blog post]
214 contains some interesting technical insights.
215
216## WebGL canvas (3D)
217* https://bobcob7.github.io/wasm-basic-triangle/[Basic triangle] (https://github.com/bobcob7/wasm-basic-triangle[source code]) - Creates a basic triangle in WebGL
218* https://bobcob7.github.io/wasm-rotating-cube/[Rotating cube] (https://github.com/bobcob7/wasm-rotating-cube[source code]) - Creates a rotating cube in WebGL
219* https://stdiopt.github.io/gowasm-experiments/splashy[Splashy] (https://github.com/stdiopt/gowasm-experiments/tree/master/splashy[source code]) - Click around on the screen to generate paint...
220
Justin Clift1322f1a2018-11-02 14:44:21 +1100[diff] [blame]221# Reducing the size of Wasm files
222
223At present, Go generates large Wasm files, with the smallest possible size being around ~2MB. If your Go code imports libraries, this file size can increase dramatically. 10MB+ is common.
224
225There are two main ways (for now) to reduce this file size:
226
2271. gz compress the .wasm file - This reduces things reasonably well. For example, the ~2MB (minimum file size) example Wasm will compress down to around 500kB.
228
joonas.fi6583ee62018-12-02 14:14:29 +0200[diff] [blame]2292. Use https://github.com/aykevl/tinygo[TinyGo] to generate the Wasm file instead. TinyGo is a subset of the Go language targeted for embedded devices, and recently added a WebAssembly output target. While it does have limitations (not a full Go implementation), it is still fairly capable and the generated Wasm files are... Tiny. ~10kB isn't unusual. This project is also very actively developed, so its capabilities are expanding out quickly.
Justin Cliftc1b68852018-10-26 00:23:01 +1100[diff] [blame]230
231# Other WebAssembly resources
232
233* https://github.com/mbasso/awesome-wasm[Awesome-Wasm] - An extensive list of further Wasm resources. Not Go specific.