fluencelabs/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/fluencelabs/wasm-bindgen synced 2025-03-17 10:40:50 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1369 from alexcrichton/targets

Browse Source 
Replace target flags with `--target`
This commit is contained in:
Alex Crichton 2019-03-21 16:06:42 -05:00 committed by GitHub
commit 0e864a4855
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 125 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
crates/cli-support/src/js/mod.rs
View File

@ -179,7 +179,7 @@ impl<'a> Context<'a> {
}
}
OutputMode::Web => {
// In web mode there's no need to export the internals of
// In web mode there's no need to export the internals of
// wasm-bindgen as we're not using the module itself as the
// import object but rather the `__exports` map we'll be
// initializing below.
@ -300,8 +300,8 @@ impl<'a> Context<'a> {
}
/// Performs the task of actually generating the final JS module, be it
/// `--no-modules`, `--web`, or for bundlers. This is the very last step
/// performed in `finalize`.
/// `--target no-modules`, `--target web`, or for bundlers. This is the very
/// last step performed in `finalize`.
fn finalize_js(&mut self, module_name: &str, needs_manual_start: bool) -> (String, String) {
let mut js = String::new();
if self.config.mode.no_modules() {
@ -312,8 +312,9 @@ impl<'a> Context<'a> {
// import the wasm file in one way or another.
let mut init = String::new();
match &self.config.mode {
// In `--no-modules` mode we need to both expose a name on the
// global object as well as generate our own custom start function.
// In `--target no-modules` mode we need to both expose a name on
// the global object as well as generate our own custom start
// function.
OutputMode::NoModules { global } => {
js.push_str("const __exports = {};\n");
js.push_str("let wasm;\n");
@ -352,8 +353,8 @@ impl<'a> Context<'a> {
// With a browser-native output we're generating an ES module, but
// browsers don't support natively importing wasm right now so we
// expose the same initialization function as `--no-modules` as the
// default export of the module.
// expose the same initialization function as `--target no-modules`
// as the default export of the module.
OutputMode::Web => {
js.push_str("const __exports = {};\n");
self.imports_post.push_str("let wasm;\n");
@ -755,7 +756,7 @@ impl<'a> Context<'a> {
if !me.config.mode.no_modules() && !me.config.mode.web() {
bail!(
"`wasm_bindgen::module` is currently only supported with \
--no-modules and --web"
`--target no-modules` and `--target web`"
);
}
Ok(format!(
@ -2832,8 +2833,8 @@ impl<'a, 'b> SubContext<'a, 'b> {
import: &decode::Import<'b>,
item: &'b str,
) -> Result<Import<'b>, Error> {
// First up, imports don't work at all in `--no-modules` mode as we're
// not sure how to import them.
// First up, imports don't work at all in `--target no-modules` mode as
// we're not sure how to import them.
let is_local_snippet = match import.module {
decode::ImportModule::Named(s) => self.cx.local_modules.contains_key(s),
decode::ImportModule::RawNamed(_) => false,
@ -2843,14 +2844,14 @@ impl<'a, 'b> SubContext<'a, 'b> {
if self.cx.config.mode.no_modules() {
if is_local_snippet {
bail!(
"local JS snippets are not supported with `--no-modules`; \
use `--web` or no flag instead",
"local JS snippets are not supported with `--target no-modules`; \
use `--target web` or no flag instead",
);
}
if let decode::ImportModule::Named(module) = &import.module {
bail!(
"import from `{}` module not allowed with `--no-modules`; \
use `--nodejs`, `--web`, or no flag instead",
"import from `{}` module not allowed with `--target no-modules`; \
use `nodejs`, `web`, or `bundler` target instead",
module
);
}
@ -2866,16 +2867,16 @@ impl<'a, 'b> SubContext<'a, 'b> {
// have a small unergonomic escape hatch for our webidl-tests tests
if env::var("WBINDGEN_I_PROMISE_JS_SYNTAX_WORKS_IN_NODE").is_err() {
bail!(
"local JS snippets are not supported with `--nodejs`; \
"local JS snippets are not supported with `--target nodejs`; \
see rustwasm/rfcs#6 for more details, but this restriction \
will be lifted in the future"
);
}
}
// Similar to `--no-modules`, only allow vendor prefixes basically for web
// apis, shouldn't be necessary for things like npm packages or other
// imported items.
// Similar to `--target no-modules`, only allow vendor prefixes
// basically for web apis, shouldn't be necessary for things like npm
// packages or other imported items.
let vendor_prefixes = self.vendor_prefixes.get(item);
if let Some(vendor_prefixes) = vendor_prefixes {
assert!(vendor_prefixes.len() > 0);

24
crates/cli-support/src/lib.rs
View File

@ -59,7 +59,9 @@ impl Bindgen {
Bindgen {
input: Input::None,
out_name: None,
mode: OutputMode::Bundler { browser_only: false },
mode: OutputMode::Bundler {
browser_only: false,
},
debug: false,
typescript: false,
demangle: true,
@ -108,7 +110,7 @@ impl Bindgen {
OutputMode::Node {
experimental_modules: false,
},
"--nodejs",
"--target nodejs",
)?;
}
Ok(self)
@ -126,9 +128,21 @@ impl Bindgen {
Ok(self)
}
pub fn bundler(&mut self, bundler: bool) -> Result<&mut Bindgen, Error> {
if bundler {
self.switch_mode(
OutputMode::Bundler {
browser_only: false,
},
"--target bundler",
)?;
}
Ok(self)
}
pub fn web(&mut self, web: bool) -> Result<&mut Bindgen, Error> {
if web {
self.switch_mode(OutputMode::Web, "--web")?;
self.switch_mode(OutputMode::Web, "--target web")?;
}
Ok(self)
}
@ -139,7 +153,7 @@ impl Bindgen {
OutputMode::NoModules {
global: "wasm_bindgen".to_string(),
},
"--no-modules",
"--target no-modules",
)?;
}
Ok(self)
@ -158,7 +172,7 @@ impl Bindgen {
pub fn no_modules_global(&mut self, name: &str) -> Result<&mut Bindgen, Error> {
match &mut self.mode {
OutputMode::NoModules { global } => *global = name.to_string(),
_ => bail!("can only specify `--no-modules-global` with `--no-modules`"),
_ => bail!("can only specify `--no-modules-global` with `--target no-modules`"),
}
Ok(self)
}

21
crates/cli/src/bin/wasm-bindgen.rs
View File

@ -21,11 +21,11 @@ Options:
-h --help Show this screen.
--out-dir DIR Output directory
--out-name VAR Set a custom output filename (Without extension. Defaults to crate name)
--nodejs Generate output that only works in node.js
--web Generate output that only works in a browser
--browser Hint that JS should only be compatible with a browser
--no-modules Generate output that only works in a browser (without modules)
--target TARGET What type of output to generate, valid
values are [web, bundler, nodejs, no-modules],
and the default is [bundler]
--no-modules-global VAR Name of the global variable to initialize
--browser Hint that JS should only be compatible with a browser
--typescript Output a TypeScript definition file (on by default)
--no-typescript Don't emit a *.d.ts file
--debug Include otherwise-extraneous debug checks in output
@ -35,6 +35,9 @@ Options:
--remove-producers-section Remove the telemetry `producers` section
--encode-into MODE Whether or not to use TextEncoder#encodeInto,
valid values are [test, always, never]
--nodejs Deprecated, use `--target nodejs`
--web Deprecated, use `--target web`
--no-modules Deprecated, use `--target no-modules`
-V --version Print the version number of wasm-bindgen
";
@ -56,6 +59,7 @@ struct Args {
flag_remove_producers_section: bool,
flag_keep_debug: bool,
flag_encode_into: Option<String>,
flag_target: Option<String>,
arg_input: Option<PathBuf>,
}
@ -89,6 +93,15 @@ fn rmain(args: &Args) -> Result<(), Error> {
let typescript = args.flag_typescript || !args.flag_no_typescript;
let mut b = Bindgen::new();
if let Some(name) = &args.flag_target {
match name.as_str() {
"bundler" => b.bundler(true)?,
"web" => b.web(true)?,
"no-modules" => b.no_modules(true)?,
"nodejs" => b.nodejs(true)?,
s => bail!("invalid encode-into mode: `{}`", s),
};
}
b.input_path(input)
.nodejs(args.flag_nodejs)?
.web(args.flag_web)?

25
examples/raytrace-parallel/build.sh
View File

@ -1,25 +0,0 @@
#!/bin/sh
set -ex
# Two critical steps are required here to get this working:
#
# * First, the Rust standard library needs to be compiled. The default version
# is not compatible with atomics so we need to compile a version, with xargo,
# that is compatible.
#
# * Next we need to compile everything with the `atomics` feature enabled,
# ensuring that LLVM will generate atomic instructions and such.
RUSTFLAGS='-C target-feature=+atomics' \
rustup run nightly xargo build --target wasm32-unknown-unknown --release
# Threading support is disabled by default in wasm-bindgen, so use an env var
# here to turn it on for our bindings generation. Also note that webpack isn't
# currently compatible with atomics, so we go with the --no-modules output.
WASM_BINDGEN_THREADS=1 \
cargo run --manifest-path ../../crates/cli/Cargo.toml \
--bin wasm-bindgen -- \
../../target/wasm32-unknown-unknown/release/raytrace_parallel.wasm --out-dir . \
--no-modules
python3 -m http.server

10
examples/without-a-bundler-no-modules/README.md
View File

@ -1,4 +1,4 @@
# Without a Bundler Using `--no-modules`
# Without a Bundler Using `--target no-modules`
[View documentation for this example online][dox]
@ -13,9 +13,9 @@ $ wasm-pack build --target no-modules
and then opening `index.html` in a browser should run the example!
Note that this example is in contrast to the [without a bundler][wab] example
which performs a similar purpose except it uses `--no-modules` instead of
`--web`. The main difference here is how the shim JS and module are loaded,
where this example uses old-school `script` tags while `--web` uses ES
modules.
which performs a similar purpose except it uses `--target no-modules` instead of
`--target web`. The main difference here is how the shim JS and module are
loaded, where this example uses old-school `script` tags while `--target web`
uses ES modules.
[wab]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler

11
examples/without-a-bundler-no-modules/index.html
View File

@ -7,11 +7,12 @@
<script src='pkg/without_a_bundler_no_modules.js'></script>
<script type=module>
// Like with the `--web` output the exports are immediately available
// but they won't work until we initialize the module. Unlike `--web`,
// however, the globals are all stored on a `wasm_bindgen` global. The
// global itself is the initialization function and then the properties of
// the global are all the exported functions.
// Like with the `--target web` output the exports are immediately
// available but they won't work until we initialize the module. Unlike
// `--target web`, however, the globals are all stored on a
// `wasm_bindgen` global. The global itself is the initialization
// function and then the properties of the global are all the exported
// functions.
//
// Note that the name `wasm_bindgen` can be configured with the
// `--no-modules-global` CLI flag

6
examples/without-a-bundler/README.md
View File

@ -7,11 +7,7 @@
You can build the example locally with:
```
$ cargo build --target wasm32-unknown-unknown --release
$ cargo run -p wasm-bindgen-cli --bin wasm-bindgen -- \
../../target/wasm32-unknown-unknown/release/without_a_bundler.wasm \
--out-dir pkg \
--web
$ wasm-pack build --target web
```
and then opening `index.html` in a browser should run the example!

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

2
src/lib.rs
View File

@ -720,7 +720,7 @@ where
/// Returns a handle to this wasm instance's `WebAssembly.Module`
///
/// Note that this is only available when the final wasm app is built with
/// `--no-modules`, it's not recommended to rely on this API yet! This is
/// `--target no-modules`, it's not recommended to rely on this API yet! This is
/// largely just an experimental addition to enable threading demos. Using this
/// may prevent your wasm module from building down the road.
#[doc(hidden)]