ashley williams
7 years ago
committed by
GitHub
commit
eb850773c2
@ -0,0 +1,50 @@ |
|||||||
|
<!DOCTYPE html> |
||||||
|
<head> |
||||||
|
<meta charset="utf-8"> |
||||||
|
<title>wasm-pack</title> |
||||||
|
<link href="https://cdnjs.cloudflare.com/ajax/libs/skeleton/2.0.4/skeleton.min.css" rel="stylesheet"> |
||||||
|
<link rel="stylesheet" href="./public/custom.css" /> |
||||||
|
</head> |
||||||
|
<body> |
||||||
|
<nav class="navbar"> |
||||||
|
<div class="container"> |
||||||
|
<ul class="navbar-list"> |
||||||
|
<li class="navbar-logo"> |
||||||
|
<a href="/"> |
||||||
|
<img src="./public/img/rustwasm.png"> |
||||||
|
</a> |
||||||
|
</a> |
||||||
|
<li class="navbar-item"> |
||||||
|
<a href="https://github.com/rustwasm/wasm-pack/issues/new/choose">File an Issue</a> |
||||||
|
</li> |
||||||
|
<li class="navbar-item"> |
||||||
|
<a href="/book">Documentation</a> |
||||||
|
</li> |
||||||
|
<li class="navbar-item"> |
||||||
|
<a href="/installer">Install</a> |
||||||
|
</li> |
||||||
|
</ul> |
||||||
|
</div> |
||||||
|
</nav> |
||||||
|
<header> |
||||||
|
<div class="container"> |
||||||
|
<div class="row"> |
||||||
|
<div class="seven columns" id="logo"> |
||||||
|
<img src="./public/img/wasm-ferris.png"alt="wasm ferris logo" /> |
||||||
|
<h1><code>wasm-pack</code></h1> |
||||||
|
<h2>📦✨ your favorite rust -> wasm workflow tool!</h2> |
||||||
|
</div> |
||||||
|
<div class="five columns" id="installer"> |
||||||
|
<a class="button button-primary" href="/installer">✨ Install wasm-pack 0.4.2 ✨</a> |
||||||
|
<p>24 July 2018 | |
||||||
|
<a href="https://github.com/rustwasm/wasm-pack/releases/tag/v0.4.2"> |
||||||
|
Release Notes |
||||||
|
</a> |
||||||
|
</p> |
||||||
|
</div> |
||||||
|
</div> |
||||||
|
</header> |
||||||
|
</div> |
||||||
|
</div> |
||||||
|
<script type="text/javascript" src="installer/wasm-pack.js"></script> |
||||||
|
</body> |
||||||
@ -0,0 +1,98 @@ |
|||||||
|
@import url('https://fonts.googleapis.com/css?family=Raleway'); |
||||||
|
|
||||||
|
.navbar { |
||||||
|
display: block; |
||||||
|
width: 100%; |
||||||
|
height: 6.5rem; |
||||||
|
background: #fff; |
||||||
|
z-index: 99; |
||||||
|
border-bottom: 1px solid #eee; |
||||||
|
} |
||||||
|
|
||||||
|
.navbar-list { |
||||||
|
list-style: none; |
||||||
|
margin-bottom: 0; |
||||||
|
} |
||||||
|
|
||||||
|
.navbar-item { |
||||||
|
position: relative; |
||||||
|
float: right; |
||||||
|
margin-bottom: 0; |
||||||
|
} |
||||||
|
|
||||||
|
.navbar-logo { |
||||||
|
position: relative; |
||||||
|
float: left; |
||||||
|
margin-bottom: 0; |
||||||
|
} |
||||||
|
|
||||||
|
.navbar-logo a img { |
||||||
|
width: 50px; |
||||||
|
} |
||||||
|
|
||||||
|
.navbar-item a { |
||||||
|
text-transform: uppercase; |
||||||
|
font-size: 11px; |
||||||
|
font-weight: 600; |
||||||
|
letter-spacing: .2rem; |
||||||
|
margin-right: 35px; |
||||||
|
text-decoration: none; |
||||||
|
line-height: 6.5rem; |
||||||
|
color: #222; |
||||||
|
} |
||||||
|
|
||||||
|
#logo, #installer { |
||||||
|
text-align: center; |
||||||
|
} |
||||||
|
|
||||||
|
#logo { |
||||||
|
padding: 50px; |
||||||
|
} |
||||||
|
|
||||||
|
#logo img { |
||||||
|
width: 80%; |
||||||
|
} |
||||||
|
|
||||||
|
#logo h1, h2 { |
||||||
|
text-align: center; |
||||||
|
} |
||||||
|
|
||||||
|
#logo h2 { |
||||||
|
font-size: 1.8rem; |
||||||
|
letter-spacing: 0.01rem; |
||||||
|
color: #222; |
||||||
|
} |
||||||
|
|
||||||
|
#installer a.button { |
||||||
|
width: 100%; |
||||||
|
height: 20%; |
||||||
|
font-size: 1.8rem; |
||||||
|
padding: 1.8rem; |
||||||
|
margin: 10rem 0 1.8rem 0; |
||||||
|
background-color: #6556EC; |
||||||
|
border-color: #6556EC; |
||||||
|
} |
||||||
|
|
||||||
|
#installer img { |
||||||
|
padding: 50px; |
||||||
|
width: 20%; |
||||||
|
} |
||||||
|
|
||||||
|
.curl { |
||||||
|
padding: 50px; |
||||||
|
} |
||||||
|
|
||||||
|
.curl p { |
||||||
|
margin-top: 50px; |
||||||
|
} |
||||||
|
|
||||||
|
.curl code { |
||||||
|
padding: 20px; |
||||||
|
font-size: 2rem; |
||||||
|
background-color: #000; |
||||||
|
color: #fff; |
||||||
|
} |
||||||
|
|
||||||
|
a { |
||||||
|
color: #6556EC; |
||||||
|
} |
||||||
|
After Width: | Height: | Size: 29 KiB |
|
After Width: | Height: | Size: 117 KiB |
@ -0,0 +1 @@ |
|||||||
|
# pack and publish |
||||||
@ -1,7 +0,0 @@ |
|||||||
# Getting Started |
|
||||||
|
|
||||||
In this section, we'll teach you how to get `wasm-pack` installed and how to setup a project |
|
||||||
to use `wasm-pack` with. |
|
||||||
|
|
||||||
- [Installation](./installation.html) |
|
||||||
- [Project Setup](./project-setup/index.html) |
|
||||||
@ -1,14 +0,0 @@ |
|||||||
## Installation |
|
||||||
|
|
||||||
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 |
|
||||||
``` |
|
||||||
@ -1,40 +0,0 @@ |
|||||||
# Manual Setup |
|
||||||
|
|
||||||
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 <mgattozzi@gmail.com>"] |
|
||||||
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" |
|
||||||
``` |
|
||||||
@ -1 +0,0 @@ |
|||||||
# Prerequisites |
|
||||||
@ -1,31 +1,35 @@ |
|||||||
# Rust |
# Rust |
||||||
|
|
||||||
`wasm-pack` is a tool written in Rust, and distributed with `cargo`. As a result, |
`wasm-pack` is a Command Line Interface tool written in Rust, and distributed with `cargo`. |
||||||
you'll need Rust and `cargo` to use `wasm-pack`. |
As a result, you'll need Rust and `cargo` to use `wasm-pack`. |
||||||
|
|
||||||
To install Rust, visit this [page](https://www.rust-lang.org/en-US/install.html). |
### Installing Rust and Cargo |
||||||
|
|
||||||
You can be sure you have Rust and Cargo installed by running: |
To install Rust, visit this [page](https://www.rust-lang.org/en-US/install.html), which will |
||||||
|
walk you through installing Rust and `cargo` on your machine using a tool called `rustup`. |
||||||
|
|
||||||
|
To confirm you have Rust and `cargo` installed, run: |
||||||
|
|
||||||
``` |
``` |
||||||
rustc --version |
rustc --version |
||||||
cargo --version |
cargo --version |
||||||
``` |
``` |
||||||
|
|
||||||
### `nightly` Rust |
### Rust Versions |
||||||
|
|
||||||
`wasm-pack` depends on `wasm-bindgen` which currently requires Rust features that |
`wasm-pack` depends on a library called `wasm-bindgen`. `wasm-bindgen` requires that you use |
||||||
have not yet been stabilized. As a result, you'll need to use a nightly version of |
Rust 1.30.0 or higher. This version is currently only available on the `nightly` or `beta` |
||||||
Rust to run `wasm-pack`. |
channels. |
||||||
|
|
||||||
You can install the nightly channel by running: |
To get the correct version of Rust, you'll use `rustup` a Rust version manager that comes |
||||||
|
bundled with Rust. Run this command to install the latest Rust on the `beta` channel: |
||||||
|
|
||||||
``` |
``` |
||||||
rustup install nightly |
rustup install beta |
||||||
``` |
``` |
||||||
|
|
||||||
You can configure rustup to always use `nightly` in a directory by running: |
You can set your project directory to always use this version of Rust by running: |
||||||
|
|
||||||
``` |
``` |
||||||
rustup override set nightly |
rustup override set beta |
||||||
``` |
``` |
||||||
|
|||||||
@ -1,5 +1,7 @@ |
|||||||
# Project Setup |
# Project Setup |
||||||
|
|
||||||
|
In this section, how to setup a `wasm-pack` project. |
||||||
|
|
||||||
There are a few things you need to do to setup a project for `wasm-pack`. |
There are a few things you need to do to setup a project for `wasm-pack`. |
||||||
We strongly recommending [using a template], but you can also set the project |
We strongly recommending [using a template], but you can also set the project |
||||||
up [manually]. |
up [manually]. |
||||||
@ -1,78 +0,0 @@ |
|||||||
# 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 |
|
||||||
|
|
||||||
### Using a Template |
|
||||||
|
|
||||||
You can create a new Rust-WebAssembly project by using the [rustwasm wasm-pack-template]. |
|
||||||
|
|
||||||
To so do, you'll need the `cargo-generate` tool. To install `cargo-generate`: |
|
||||||
|
|
||||||
``` |
|
||||||
cargo install cargo-generate |
|
||||||
``` |
|
||||||
|
|
||||||
Then run: |
|
||||||
|
|
||||||
``` |
|
||||||
cargo generate --git https://github.com/rustwasm/wasm-pack-template |
|
||||||
``` |
|
||||||
|
|
||||||
You will be prompted to give your project a name. Once you do, you will have a directory |
|
||||||
with a new project, ready to go. |
|
||||||
|
|
||||||
### Manually |
|
||||||
|
|
||||||
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 <mgattozzi@gmail.com>"] |
|
||||||
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" |
|
||||||
``` |
|
||||||
|
Before Width: | Height: | Size: 21 KiB |
@ -0,0 +1 @@ |
|||||||
|
# Template Deep Dive |
||||||
@ -0,0 +1,3 @@ |
|||||||
|
# src/lib.rs |
||||||
|
|
||||||
|
🚧 COMING SOON 🚧 |
||||||
@ -0,0 +1,3 @@ |
|||||||
|
# src/utils.rs |
||||||
|
|
||||||
|
🚧 COMING SOON 🚧 |
||||||
@ -1,90 +1,70 @@ |
|||||||
# Run The Code From npm |
# 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. |
This portion of the tutorial will help you create a [Webpack] JavaScript project that will |
||||||
|
run your WebAssembly code in the browser. |
||||||
|
|
||||||
```bash |
[Webpack]: https://webpack.js.org/ |
||||||
$ mkdir test |
|
||||||
$ cd test |
|
||||||
``` |
|
||||||
|
|
||||||
Now we need to create a `package.json` file that looks like this: |
## Scaffold a JavaScript Project |
||||||
|
|
||||||
```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 your npm username. You can expand this to be a more complete file but |
To scaffold a project that we can use our new package in, we'll use an npm template called |
||||||
we're really just trying to verify that this works! |
[`create-wasm-app`]. To use this run this command in a directory *different* than your Rust |
||||||
|
project: |
||||||
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 your `webpack.config.js` 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 |
[`create-wasm-app`]: https://github.com/rustwasm/create-wasm-app |
||||||
we'll need to setup a small html file. Create a new file called `index.html` and put this inside it: |
|
||||||
|
``` |
||||||
```html |
npm init wasm-app |
||||||
<!DOCTYPE html> |
|
||||||
<html> |
|
||||||
<head> |
|
||||||
<meta charset="utf-8"> |
|
||||||
<title>wasm-pack example</title> |
|
||||||
</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! |
This tool will ask you for the name of a project, and then create a directory with that name. |
||||||
Make a file called `index.js` and put this inside of it: |
|
||||||
|
If we look in that directory, we'll see the following: |
||||||
|
|
||||||
|
- `.gitignore`: ignores `node_modules` |
||||||
|
- `LICENSE-APACHE` and `LICENSE-MIT`: most Rust projects are licensed this way, so these are included for you |
||||||
|
- `README.md`: the file you are reading now! |
||||||
|
- `index.html`: a bare bones html document that includes the webpack bundle |
||||||
|
- `index.js`: example js file with a comment showing how to import and use a wasm pkg |
||||||
|
- `package.json` and `package-lock.json`: |
||||||
|
- pulls in devDependencies for using webpack: |
||||||
|
- [`webpack`](https://www.npmjs.com/package/webpack) |
||||||
|
- [`webpack-cli`](https://www.npmjs.com/package/webpack-cli) |
||||||
|
- [`webpack-dev-server`](https://www.npmjs.com/package/webpack-dev-server) |
||||||
|
- defines a `start` script to run `webpack-dev-server` |
||||||
|
- `webpack.config.js`: configuration file for bundling your js with webpack |
||||||
|
|
||||||
```javascript |
## Add Your npm Package |
||||||
const js = import("@MYSCOPE/wasm-add/wasm_add.js"); |
|
||||||
js.then(js => { |
The scaffolded project includes an example WebAssembly package, `hello-wasm-pack`, in your |
||||||
js.alert_add(3,2); |
`package.json`. Go into the `package.json` file, add your package, and remove the |
||||||
}); |
`hello-wasm-pack` dependency from the `"dependencies"` section. |
||||||
|
|
||||||
|
Now, open up the `index.js` file. Replace the `hello-wasm-pack` in the first line with the |
||||||
|
name of your package: |
||||||
|
|
||||||
|
```js |
||||||
|
import * as wasm from "<your package name>"; |
||||||
|
|
||||||
|
wasm.greet(); |
||||||
``` |
``` |
||||||
|
|
||||||
Since web pack [can't load wasm synchronously yet](https://github.com/webpack/webpack/issues/6615) |
## Run The Project |
||||||
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 |
Before we run our project, we need to make sure we install our dependencies: |
||||||
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 |
```bash |
||||||
$ npm install |
npm install |
||||||
$ npm run serve |
|
||||||
``` |
``` |
||||||
|
|
||||||
Then in a web browser navigate to `http://localhost:8080` you should see something like this: |
We should be ready to run our project now! To run our project we'll run: |
||||||
|
|
||||||
|
```bash |
||||||
|
npm start |
||||||
|
``` |
||||||
|
|
||||||
 |
Then in a web browser navigate to `http://localhost:8080` and you should be greeted with an |
||||||
|
alert box that says "Hello World!". |
||||||
|
|
||||||
If you did congrats you've successfully uploaded your first bit of wasm code to npm and used it |
If you did congrats you've successfully uploaded your first bit of wasm code to npm and used it |
||||||
properly! |
properly! |
||||||
|
|||||||
@ -1 +0,0 @@ |
|||||||
# Writing a Rust-WebAssembly Library |
|
||||||
Loading…
Reference in new issue