Merge pull request #99 from data-pup/add-example-usage-documentation

Add example usage documentation

Author: mgattozzi

docs/init.md

@@ -0,0 +1,33 @@
+# wasm-pack init
+
+The `wasm-pack init` command creates the files neccessary for JavaScript
+interoperability and for publishing a package to npm. This involves compiling
+your code to wasm and generating a pkg folder. This pkg folder will contain the
+wasm binary, a JS wrapper file, your `README`, and a `package.json` file.
+
+## Path
+
+The `wasm-pack init` command can be given an optional path argument, e.g.:
+
+```
+wasm-pack init examples/js-hello-world
+```
+
+This path should point to a directory that contains a `Cargo.toml` file. If no
+path is given, the `init` command will run in the current directory.
+
+## Scope
+
+The init command also accepts an optional `--scope` argument. This will scope
+your package name, which is useful if your package name might conflict with
+something in the public registry. For example:
+
+```
+wasm-pack init examples/js-hello-world --scope test
+```
+
+This command would create a `package.json` file for a package called
+`@test/js-hello-world`. For more information about scoping, you can refer to
+the npm documentation [here][npm-scope-documentation].
+
+[npm-scope-documentation]: https://docs.npmjs.com/misc/scope

docs/pack.md

@@ -0,0 +1,10 @@
+# wasm-pack pack
+
+The `wasm-pack pack` command is used to create a tarball of your wasm project
+using the `npm pack` command. This is useful if you would like to create a
+local tarball containing your package, without publishing it to the npm
+registry.
+
+You can read more about the `npm pack` command [here][npm-pack-documentation].
+
+[npm-pack-documentation]: https://docs.npmjs.com/cli/pack

docs/prerequisites.md

@@ -0,0 +1,29 @@
+# Prerequisites
+
+## Rust and npm
+
+Before installing `wasm-pack`, you should make sure that you have already
+installed Rust and npm. You can confirm that these are installed using the
+following commands:
+
+```sh
+# Check if Rust is installed.
+cargo --version
+
+# Check if npm is installed.
+npm --version
+```
+
+You can find more information about installing Rust
+[here][rust-wasm-install-info] and more information about installing npm
+[here][npm-install-info].
+
+## Sign Up For npm
+
+You will need to create an npm account if you plan on publishing your package to
+the npm public registry. You can find information about signing up for npm
+[here][npm-signup-info].
+
+[rust-wasm-install-info]: https://rust-lang-nursery.github.io/rust-wasm/setup.html
+[npm-install-info]: https://www.npmjs.com/get-npm
+[npm-signup-info]: https://www.npmjs.com/signup

docs/publish.md

@@ -0,0 +1,4 @@
+# wasm-pack publish
+
+The `wasm-pack publish` command will create a tarball of your wasm project,
+and publish it to the npm registry.

docs/setup.md

@@ -0,0 +1,57 @@
+# Setup
+
+## Installing wasm-pack
+
+You can install `wasm-pack` using the following command:
+
+```
+cargo install wasm-pack
+```
+
+If you have already installed `wasm-pack` and want to install a newer version,
+you can use the `--force` option, like this:
+
+```
+cargo install wasm-pack --force
+```
+
+## Project Initialization
+
+You can create a new Rust project named `my-lib` using this command.
+
+```
+cargo new --lib my-lib
+```
+
+The `--lib` flag specifies that the project is a library, which is important
+because we will be calling this code from JavaScript.
+
+### Cargo.toml changes
+
+You will need to add `wasm-bindgen` to your `Cargo.toml` in the dependencies
+section. `wasm-bindgen` is a tool that facilitates interoperability between
+wasm modules and JavaScript.
+
+Next, add a `[lib]` section, with a new field named `crate-type` set to
+`"cdylib"`. This specifies that the library is a C compatible dynamic library,
+which helps `cargo` pass the correct flags to the Rust compiler when targeting
+`wasm32`.
+
+After making these changes, your `Cargo.toml` file should look something like
+this:
+
+```
+[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.2"
+```