Add documentation for building programs using AssemblyScript. (#1782)

* Add documentation for building programs using AssemblyScript.

* Add the assemblyscript hello world as an example and display it inline.

* Move the AssemblyScript hello world into the docs directory.

That way Cargo doesn't try to run it like a Rust example.

docs/SUMMARY.md

@@ -39,6 +39,7 @@
 - [Writing WebAssembly](./wasm.md)
   - [Rust](./wasm-rust.md)
   - [C/C++](./wasm-c.md)
+  - [AssemblyScript](./wasm-assemblyscript.md)
   - [WebAssembly Text Format (`*.wat`)](./wasm-wat.md)
   - [Example: Markdown Parser](./wasm-markdown.md)
 - [Stability](stability.md)

docs/assemblyscript-hello-world/package-lock.json

@@ -0,0 +1,35 @@
+{
+  "name": "wasi-hello-world",
+  "version": "1.0.0",
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "as-wasi": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/as-wasi/-/as-wasi-0.1.1.tgz",
+      "integrity": "sha512-7PrSjsD/K2Pg95/2fu+4RJCfZLiuM0w0k5lMceaCf73EvH+7WPQTM1WW/vS0cizRTaEDj8Wz5ttoZBJSvsZpBQ=="
+    },
+    "assemblyscript": {
+      "version": "0.10.0",
+      "resolved": "https://registry.npmjs.org/assemblyscript/-/assemblyscript-0.10.0.tgz",
+      "integrity": "sha512-ErUNhHboD+zsB4oG6X1YICDAIo27Gq7LeNX6jVe+Q0W5cI51/fHwC8yJ68IukqvupmZgYPdp1JqqRXlS+BrUfA==",
+      "dev": true,
+      "requires": {
+        "binaryen": "93.0.0-nightly.20200514",
+        "long": "^4.0.0"
+      }
+    },
+    "binaryen": {
+      "version": "93.0.0-nightly.20200514",
+      "resolved": "https://registry.npmjs.org/binaryen/-/binaryen-93.0.0-nightly.20200514.tgz",
+      "integrity": "sha512-SRRItmNvhRVfoWWbRloO4i8IqkKH8rZ7/0QWRgLpM3umupK8gBpo9MY7Zp3pDysRSp+rVoqxvM5x4tFyCSa9zw==",
+      "dev": true
+    },
+    "long": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/long/-/long-4.0.0.tgz",
+      "integrity": "sha512-XsP+KhQif4bjX1kbuSiySJFNAehNxgLb6hPRGJ9QsUr8ajHkuXGdrHmFUTUUXhDwVX2R5bY4JNZEwbUiMhV+MA==",
+      "dev": true
+    }
+  }
+}

docs/assemblyscript-hello-world/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "wasi-hello-world",
+  "version": "1.0.0",
+  "description": "Hello world in Wasi with AS and as-wasi",
+  "main": "index.js",
+  "scripts": {
+    "build": "asc wasi-hello-world.ts -b wasi-hello-world.wasm -t wasi-hello-world.wat --runtime half",
+    "wasmtime": "wasmtime wasi-hello-world.wasm"
+  },
+  "author": "Aaron Turner",
+  "license": "MIT",
+  "devDependencies": {
+    "assemblyscript": "^0.10.0"
+  },
+  "dependencies": {
+    "as-wasi": "^0.1.1"
+  }
+}

docs/assemblyscript-hello-world/wasi-hello-world.ts

@@ -0,0 +1,5 @@
+import "wasi"
+
+import {Console} from "as-wasi"
+Console.log('Hello World!\n');
+

docs/wasm-assemblyscript.md

@@ -0,0 +1,53 @@
+# AssemblyScript
+
+[AssemblyScript] 0.10.0 includes support for targeting WASI. To use it, add
+`import "wasi"` at the top of your entrypoint file.
+
+To create a program which can be run directly as a command, pass `--runtime half`
+to the AssemblyScript linker. This selects the [half runtime], which ensures that
+the generated wasm module doesn't contain any extraneous exports. (This isn't
+strictly required today, but the handling of extraneous exports may change in
+the future, so it's encouraged. As a bonus, it also reduces code size.)
+
+To create a program which can be loaded as a library and used from other modules,
+no special options are needed.
+
+Let's walk through a simple hello world example.
+
+## `wasi-hello-world.ts`
+
+```typescript
+{{#include ./assemblyscript-hello-world/wasi-hello-world.ts}}
+```
+
+This uses [as-wasi] as a dependency to make working with the AssemblyScript WASI
+bindings easier. Then, you can run:
+
+```sh
+asc wasi-hello-world.ts -b wasi-hello-world.wasm
+```
+
+to compile it to wasm, and
+
+```sh
+wasmtime wasi-hello-world.wasm
+```
+
+to run it from the command-line. Or you can instantiate it using the [Wasmtime API].
+
+## `package.json`
+
+It can also be packaged using a `package.json` file:
+
+```json
+{{#include ./assemblyscript-hello-world/package.json}}
+```
+
+You can also [browse this source code online][code] and clone the wasmtime
+repository to run the example locally.
+
+[code]: https://github.com/bytecodealliance/wasmtime/blob/master/docs/assemblyscript-hello-world
+[AssemblyScript]: https://assemblyscript.org
+[as-wasi]: https://github.com/jedisct1/as-wasi
+[half runtime]: https://docs.assemblyscript.org/details/runtime#runtime-variants
+[Wasmtime API]: ./lang.md

docs/wasm.md

@@ -9,4 +9,5 @@ check out your language's documentation for WebAssembly as well.
 
 * [Rust](wasm-rust.md)
 * [C/C++](wasm-c.md)
+* [AssemblyScript](wasm-assemblyscript.md)
 * [WebAssembly Text Format (`*.wat`)](wasm-wat.md)