mirror of
https://github.com/fluencelabs/wasm-bindgen
synced 2025-03-16 02:00:51 +00:00
Merge pull request #1369 from alexcrichton/targets
Replace target flags with `--target`
This commit is contained in:
commit
0e864a4855
@ -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);
|
||||
|
@ -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,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)?
|
||||
|
@ -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
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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!
|
||||
|
@ -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
|
||||
|
@ -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]
|
||||
|
||||
|
@ -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/
|
||||
|
@ -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
|
||||
|
@ -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)]
|
||||
|
Loading…
x
Reference in New Issue
Block a user