Merge pull request rustwasm#86 from mgattozzi/wasm-pack

Add the wasm-pack tutorial

Author: ashleygwilliams

src/SUMMARY.md

@@ -7,3 +7,11 @@
 - [Tools](./tools.md)
 - [Workflows](./workflows.md)
 - [JavaScript Interoperation](./js-ffi.md)
+- [Tutorials](./tutorials.md)
+    - [wasm-pack](./wasm-pack/introduction.md)
+        - [Setup](./wasm-pack/setup.md)
+        - [Project Initialization](./wasm-pack/initialize.md)
+        - [Rust Code](./wasm-pack/rust-code.md)
+        - [Package Code For npm](./wasm-pack/package-code.md)
+        - [Run The Code From npm](./wasm-pack/run-the-code.md)
+        - [Next Steps](./wasm-pack/next-steps.md)

src/tools.md

@@ -15,6 +15,7 @@ However, since Rust has the potential to be used for both development and toolin
 - [wasmparser] - A wasm binary decoder with optional validation, in Rust
 - [wasmtext] - prints wasm modules in text format, in Rust
 - [wasmstandalone] - standalone JIT-based wasm runner, in Rust, using Cretonne, in early development
+- [wasm-pack] - Package up your wasm for distribution on npm
 
 There's also plenty of _space for tooling to be be built or rewritten in Rust_ for better synergy with the ecosystem. Some of them include:
 - [A wasm size profiler][wasmsizeprofiler]
@@ -36,3 +37,4 @@ This page is meant to be a living document, so feel free to send us a pull reque
 [wasmstandalone]: https://github.com/sunfishcode/wasmstandalone
 [wasmsizeprofiler]: https://github.com/rust-lang-nursery/rust-wasm/issues/20
 [ewasm]: https://github.com/ewasm
+[wasm-pack]: https://github.com/ashleygwilliams/wasm-pack

src/tutorials.md

@@ -0,0 +1,4 @@
+# Tutorials
+
+There are a wide variety of tools available in the ecosystem and we want to provide a centralized
+way to show you how to get using them more in depth than a basic readme.

src/wasm-pack/initialize.md

@@ -0,0 +1,81 @@
+# Project Initialization
+
+Now that we've installed all of our tools and setup our npm account we can actually start coding!
+We'll be writing up a small crate that adds two numbers and outputs the numbers. While this will
+be a simple example, we're really trying to focus on how to use wasm-pack. You'll be provided links
+to other resources so you can make more complicated code to package and ship them to npm!
+
+Let's get started then! First off run this command to create our project:
+
+```bash
+$ cargo new --lib wasm-add
+```
+
+This will create a new Rust project in a directory called `wasm-add`. We've also specified that
+we're building a library, since we'll be calling this code from JS.
+
+Now just:
+
+```bash
+$ cd wasm-add
+```
+
+You'll find everything in here ready to get started. First though we'll need to add a dependency to
+our code and make a few small changes. Open up your `Cargo.toml` file. You should see something like
+this inside:
+
+```toml
+[package]
+name = "wasm-add"
+version = "0.1.0"
+authors = ["Michael Gattozzi <[email protected]>"]
+
+[dependencies]
+```
+
+This configuration file sets up everything we need to get started but we'll need a few extra fields
+and settings to get this to work for wasm and be ready for npm
+
+```toml
+[package]
+name = "wasm-add"
+version = "0.1.0"
+authors = ["Michael Gattozzi <[email protected]>"]
+description = "Code used to demonstrate how to use wasm-pack"
+license = "MIT/Apache-2.0"
+repository = "https://github.com/mgattozzi/wasm-add"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wasm-bindgen="0.1"
+```
+
+First off lets look at the last three fields added to the package section `description`, `license`,
+and `repository` npm requires this metadata and so `wasm-pack` won't package your code up until you
+have them set. There are more fields that you can add that are more specific to `crates.io` that you
+can find [here](https://doc.rust-lang.org/cargo/reference/manifest.html) but for the sake of this
+tutorial that's all you need for that section.
+
+You'll also notice we add a new section titled `[lib]`. In here we added this line:
+
+```toml
+crate-type = ["cdylib"]
+```
+
+Normally rust compiles the code for the library in a format meant for other Rust packages. We want
+our code to work with wasm though! We specify that it's a dynamic library that's C compatible. This
+sounds a bit weird but the `wasm32` target will know to interpret this option and instead produce
+a wasm binary properly. This is meant to get `cargo` to pass the right parameters to the compiler!
+
+Alright the last thing we added was this to the `[dependencies]` section:
+
+```toml
+wasm-bindgen="0.1"
+```
+
+This is the `wasm-bindgen` crate. We'll be using it very shortly to make our functions work nicely
+with wasm and not have to worry about a lot of nitty gritty details.
+
+We've got our package's metadata all setup so let's actually write some code!

src/wasm-pack/introduction.md

@@ -0,0 +1,17 @@
+# Introduction
+
+`wasm-pack` is a brand new tool designed to make packaging up binaries that include wasm (that may
+or may not have JS in them) and make publishing them on npm easy to do. We can't necessarily
+distribute Rust code to developers directly and expect them
+to build it from scratch. npm is used to install packages for frontend work but it doesn't know how
+to compile Rust! With wasm though it's not a problem. Once it's compiled it's all good to go.
+However, getting it ready to be distributed, packaging it up properly for npm, and then sending it
+to npm can be a bit of a hassle. `wasm-pack` is here to make that easier.
+
+We'll step through creating a simple Rust library, using `wasm-pack` to get it ready for
+distribution, sending it to npm, then using it as a package from npm to verify it works!
+
+As with all software in the early stages this is bleeding edge! Expect some nicks and bruises! If
+you run into issues or a bug please file an issue over at it's [repo].
+
+[repo]: https://github.com/ashleygwilliams/wasm-pack/issues

src/wasm-pack/next-steps.md

@@ -0,0 +1,6 @@
+# Next Steps
+
+This was an introduction to wasm-pack but also using wasm code from npm. From here you could
+actually improve on the project setup, expand out what your wasm code can actually do, or expand out
+how you would use the package you've created. The whole wasm space is completely open so there's no
+limit to what you can and can't do really! Go out there and try some cool new things. Happy hacking!

src/wasm-pack/package-code.md

@@ -0,0 +1,37 @@
+# Package Code for npm
+
+We've made our code so now we need to package it all up. In your project directory run the following
+command:
+
+```bash
+$ wasm-pack init --scope MYSCOPE
+```
+
+where `MYSCOPE` is your name or something. Normally you could just type `wasm-pack init` but since
+other people are doing this tutorial as well we don't want conflicts with the `wasm-add` package
+name! This command when run does a few things:
+
+1. It'll compile your code to wasm if you haven't already
+2. It'll generate a pkg folder with the wasm file, a JS wrapper file around the wasm, your README,
+   and a `package.json` file.
+
+This is everything you need to upload your code to npm! Let's do just that!
+
+First off you'll need to login to npm with the account you made earlier if you didn't already have
+one:
+
+```bash
+$ npm login
+```
+
+Next you'll need to go into the `pkg` directory and actually upload the package:
+
+```bash
+$ cd pkg
+$ npm publish --access=public
+```
+
+Now normally if things are not scoped you can just do `npm publish` but if you give it a scope
+you'll need to tell npm that this is actually public so it can publish it. We need to do that here
+since we gave our packages a scope to avoid conflicting with each other! Next up is actually running
+the code and verifying we got it from npm and how we can use that code.

src/wasm-pack/run-the-code.md

@@ -0,0 +1,88 @@
+# Run The Code From npm
+
+Alright let's make a new small directory to test that we can now run this code and pull it from npm.
+
+```bash
+$ mkdir test
+$ cd test
+```
+
+Now we need to create a `package.json` file that looks like this:
+
+```json
+{
+  "scripts": {
+    "serve": "webpack-dev-server"
+  },
+  "dependencies": {
+    "@MYSCOPE/wasm-add": "^0.1.0"
+  },
+  "devDependencies": {
+    "webpack": "^4.0.1",
+    "webpack-cli": "^2.0.10",
+    "webpack-dev-server": "^3.1.0"
+  }
+}
+```
+
+where `MYSCOPE` is whatever you used before. You can expand this to be a more complete file but
+we're really just trying to verify that this works!
+
+Next up we'll need to create a small webpack configuration so that we can use the
+`webpack-dev-server` to serve the wasm file properly. It should be noted that webpack isn't
+a requirement. It's just what was chosen for this tutorial. You just need something to server the
+code! Here's what it should look like:
+
+```javascript
+const path = require('path');
+module.exports = {
+  entry: "./index.js",
+  output: {
+    path: path.resolve(__dirname, "dist"),
+    filename: "index.js",
+  },
+  mode: "development"
+};
+```
+
+This tells webpack that if it's going to start things up use `index.js`. Before we do that though
+we'll need to setup a small html file. Create a new file called `index.html` and put this inside it:
+
+```html
+<html>
+  <head>
+    <meta content="text/html;charset=utf-8" http-equiv="Content-Type"/>
+  </head>
+  <body>
+    <script src='./index.js'></script>
+  </body>
+</html>
+```
+
+We're almost set. Now we need to setup our JS file so that we can run some wasm code!
+Make a file called `index.js` and put this inside of it:
+
+```javascript
+const js = import("./node_modules/@MYSCOPE/wasm-add/wasm_add.js");
+js.then(js => {
+  js.alert_add(3,2);
+});
+```
+
+Since web pack [can't load wasm synchronously yet](https://github.com/webpack/webpack/issues/6615)
+we are using the import statement above followed
+by the promise in order to load it properly. This is what lets us then call `alert_add`. We're
+importing from the `node_module` folder we haven't gotten yet so let's import all of our
+dependencies finally and run the example!
+
+```bash
+$ npm install
+$ npm run serve
+```
+
+Then in a web browser navigate to `http://localhost:8080` you should see something like this:
+
+![An alert box saying "Hello from Rust! 3 + 2 = 5"](/wasm-pack/wasm-pack.png)
+
+If you did congrats you've successfully uploaded your first bit of wasm code to npm and used it
+properly!