fluencelabs/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/fluencelabs/wasm-bindgen synced 2025-06-22 09:11:35 +00:00
Code Issues Projects Releases Wiki Activity

Replace target flags with --target

Browse Source 
This commit deprecates the `--web`, `--no-modules`, and `--nodejs` flags
in favor of one `--target` flag. The motivation for this commit is to be
consistent between `wasm-bindgen` and `wasm-pack` so documentation for
one is applicable for the other (so we don't have to document everywhere
what the translation is between flags). Additionally this should make it
a bit easier to add new targets (if necessary) in the future as it won't
add to the proliferation of flags.

For now the old flags (like `--web`) continue to be accepted, but
they'll be removed during the next set of breaking changes for
`wasm-bindgen`.
This commit is contained in:
Alex Crichton
2019-03-19 11:25:13 -07:00
parent 93cab3d755
commit 995be7c027
12 changed files with 125 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
guide/src/examples/without-a-bundler.md
View File

@ -4,12 +4,12 @@
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler
This example shows how the `--web` flag can be used load code in a
This example shows how the `--target web` flag can be used load code in a
browser directly. For this deployment strategy bundlers like Webpack are not
required. For more information on deployment see the [dedicated
documentation][deployment].
First let's take a look at the code and see how when we're using `--web`
First let's take a look at the code and see how when we're using `--target web`
we're not actually losing any functionality!
```rust
@ -27,18 +27,17 @@ what it means to deploy without a bundler.
[deployment]: ../reference/deployment.html
## Using the older `--no-modules`
## Using the older `--target no-modules`
[View full source code][code]
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler-no-modules
The older version of using `wasm-bindgen` without a bundler is to use the
`--no-modules` flag to the `wasm-bindgen` CLI. This corresponds to `--target
no-modules` in `wasm-pack`.
`--target no-modules` flag to the `wasm-bindgen` CLI.
While similar to the newer `--web`, the `--no-modules` flag has a few
caveats:
While similar to the newer `--target web`, the `--target no-modules` flag has a
few caveats:
* It does not support [local JS snippets][snippets]
* It does not generate an ES module

30
guide/src/reference/cli.md
View File

@ -22,33 +22,19 @@ wasm-bindgen [options] ./target/wasm32-unknown-unknown/release/crate.wasm
The target directory to emit the JavaScript bindings, TypeScript definitions,
processed `.wasm` binary, etc...
### `--nodejs`
### `--target`
This flag will tailor output for Node instead of browsers, allowing for native
usage of `require` of the generated JS and internally using `require` instead of
ECMAScript modules. When using this flag no further postprocessing (aka a
bundler) should be necessary to work with the wasm.
For more information about this see the section on [deployment]
This flag indicates what flavor of output what `wasm-bindgen` should generate.
For example it could generate code to be loaded in a bundler like Webpack, a
native web page, or Node.js. For a full list of options to pass this flag, see
the section on [deployment]
[deployment]: deployment.html
### `--web`
### `--no-modules-global VAR`
This flag will generate output suitable for loading natively in browsers today.
The generated JS shims are an ES module which export a `default` instantiation
function, like `--no-modules` below.
For more information about this see the section on [deployment]
### `--no-modules` and `--no-modules-global VAR`
The default output of `wasm-bindgen` uses ECMAScript modules. These options
indicate that ECMAScript modules should *not* be used, and that output should be
tailored for a properties on the JavaScript global object (e.g. `window`).
The `--no-modules-global VAR` option makes `VAR` the global property that the
JavaScript bindings are attached to.
When `--target no-modules` is used this flag can indicate what the name of the
global to assign generated bindings to.
For more information about this see the section on [deployment]

55
guide/src/reference/deployment.md
View File

@ -5,12 +5,31 @@ locations unfortunately isn't a trivial task to do. This page hopes to serve
as documentation for the various known options, and as always PRs are welcome
to update this if it's out of date!
The methods of deployment and integration here are primarily tied to the
`--target` flag. Note that the `--target` flag of `wasm-pack` and `wasm-bindgen`
should behave the same way in this respect. The values possible here are:
| Value | Summary |
|-----------------|------------------------------------------------------------|
| [`bundler`] | Suitable for loading in bundlers like Webpack |
| [`web`] | Directly loadable in a web browser |
| [`nodejs`] | Loadable via `require` as a Node.js module |
| [`no-modules`] | Like `web`, but older and doesn't use ES modules |
[`bundler`]: #bundlers
[`web`]: #without-a-bundler
[`no-modules`]: #without-a-bundler
[`nodejs`]: #nodejs
## Bundlers
The default output of `wasm-bindgen` assumes a model where the wasm module
itself is natively an ES module. This model, however, not natively implemented
in any JS implementation at this time. As a result, to consume the default
output of `wasm-bindgen` you will need a bundler of some form.
**`--target bundler`**
The default output of `wasm-bindgen`, or the `bundler` target, assumes a model
where the wasm module itself is natively an ES module. This model, however, not
natively implemented in any JS implementation at this time. As a result, to
consume the default output of `wasm-bindgen` you will need a bundler of some
form.
> **Note**: the choice of this default output was done to reflect the trends of
> the JS ecosystem. While tools other than bundlers don't support wasm files as
@ -27,37 +46,39 @@ necessary.
## Without a Bundler
**`--target web` or `--target no-modules`**
If you're not using a bundler but you're still running code in a web browser,
`wasm-bindgen` still supports this! For this use case you'll want to use the
`--web` flag. You can check out a [full example][nomex] in the
`--target web` flag. You can check out a [full example][nomex] in the
documentation, but the highlights of this output are:
* When using `wasm-bindgen` directly you'll pass `--web`.
* When compiling you'll pass `--target web` to `wasm-pack` (or `wasm-bindgen`
directly).
* The output can natively be included on a web page, and doesn't require any
further postprocessing. The output is included as an ES module.
* The `--web` mode is not able to use NPM dependencies.
* The `--target web` mode is not able to use NPM dependencies.
* You'll want to review the [browser requirements] for `wasm-bindgen` because
no polyfills will be available.
> **Note**: currently `--web` is not supported in `wasm-pack` because it is
> a very recent addition to `wasm-bindgen`, but support will be added soon!
[nomex]: ../examples/without-a-bundler.html
[rfc1]: https://github.com/rustwasm/rfcs/pull/6
[rfc2]: https://github.com/rustwasm/rfcs/pull/8
[browser requirements]: browser-support.html
The `wasm-bindgen` CLI also supports an output mode called `--no-modules` which
is similar to `--web` in that it requires manual initialization of the wasm
and is intended to be included in web pages without any further postprocessing.
See the [without a bundler example][nomex] for some more information about
`--no-modules`, which corresponds to `--target no-modules` in `wasm-pack`.
The CLI also supports an output mode called `--target no-modules` which is
similar to the `web` target in that it requires manual initialization of the
wasm and is intended to be included in web pages without any further
postprocessing. See the [without a bundler example][nomex] for some more
information about `--target no-modules`.
## Node.js
**`--target nodejs`**
If you're deploying WebAssembly into Node.js (perhaps as an alternative to a
native module), then you'll want to pass the `--target nodejs` flag to
`wasm-pack` or the `--nodejs` flag to `wasm-bindgen`.
`wasm-pack` or `wasm-bindgen`.
Like the "without a bundler" strategy, this method of deployment does not
require any further postprocessing. The generated JS shims can be `require`'d
@ -72,4 +93,4 @@ which is currently Node 8 and above.
If you'd like to deploy compiled WebAssembly to NPM, then the tool for the job
is [`wasm-pack`]. More information on this coming soon!
[`wasm-pack`]: https://rustwasm.github.io/wasm-pack/book/
[`wasm-pack`]: https://rustwasm.github.io/docs/wasm-pack/

9
guide/src/reference/js-snippets.md
View File

@ -64,11 +64,12 @@ are important to be aware of. Many of these are temporary though!
this. For now, though, js snippets must be standalone modules and can't import
from anything else.
* Only `--web` and the default bundler output mode are supported. To support
`--nodejs` we'd need to translate ES module syntax to CommonJS (this is
* Only `--target web` and the default bundler output mode are supported. To
support `--target nodejs` we'd need to translate ES module syntax to CommonJS
(this is
planned to be done, just hasn't been done yet). Additionally to support
`--no-modules` we'd have to similarly translate from ES modules to something
else.
`--target no-modules` we'd have to similarly translate from ES modules to
something else.
* Paths in `module = "..."` must currently start with `/`, or be rooted at the
crate root. It is intended to eventually support relative paths like `./` and