Merge pull request #1328 from alexcrichton/switch-to-web

Switch the `--browser` argument to `--web`
This commit is contained in:
Alex Crichton 2019-03-07 15:25:26 -06:00 committed by GitHub
commit a7e7f8b5e1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 71 additions and 46 deletions

View File

@ -166,7 +166,7 @@ impl<'a> Context<'a> {
format!("__exports.{} = {};\n", name, contents)
}
}
OutputMode::Bundler
OutputMode::Bundler { .. }
| OutputMode::Node {
experimental_modules: true,
} => {
@ -178,8 +178,8 @@ impl<'a> Context<'a> {
format!("export const {} = {};\n", name, contents)
}
}
OutputMode::Browser => {
// In browser mode there's no need to export the internals of
OutputMode::Web => {
// 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.
@ -202,7 +202,7 @@ impl<'a> Context<'a> {
};
self.global(&global);
if self.config.mode.browser() {
if self.config.mode.web() {
self.global(&format!("__exports.{} = {0};", name));
}
}
@ -300,7 +300,7 @@ impl<'a> Context<'a> {
}
/// Performs the task of actually generating the final JS module, be it
/// `--no-modules`, `--browser`, or for bundlers. This is the very last step
/// `--no-modules`, `--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();
@ -340,7 +340,7 @@ impl<'a> Context<'a> {
// With Bundlers and modern ES6 support in Node we can simply import
// the wasm file as if it were an ES module and let the
// bundler/runtime take care of it.
OutputMode::Bundler
OutputMode::Bundler { .. }
| OutputMode::Node {
experimental_modules: true,
} => {
@ -354,7 +354,7 @@ impl<'a> Context<'a> {
// 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.
OutputMode::Browser => {
OutputMode::Web => {
js.push_str("const __exports = {};\n");
self.imports_post.push_str("let wasm;\n");
init = self.gen_init(&module_name, needs_manual_start);
@ -752,10 +752,10 @@ impl<'a> Context<'a> {
})?;
self.bind("__wbindgen_module", &|me| {
if !me.config.mode.no_modules() && !me.config.mode.browser() {
if !me.config.mode.no_modules() && !me.config.mode.web() {
bail!(
"`wasm_bindgen::module` is currently only supported with \
--no-modules"
--no-modules and --web"
);
}
Ok(format!(
@ -2843,13 +2843,13 @@ impl<'a, 'b> SubContext<'a, 'b> {
if is_local_snippet {
bail!(
"local JS snippets are not supported with `--no-modules`; \
use `--browser` or no flag instead",
use `--web` or no flag instead",
);
}
if let decode::ImportModule::Named(module) = &import.module {
bail!(
"import from `{}` module not allowed with `--no-modules`; \
use `--nodejs`, `--browser`, or no flag instead",
use `--nodejs`, `--web`, or no flag instead",
module
);
}

View File

@ -36,8 +36,8 @@ pub struct Bindgen {
}
enum OutputMode {
Bundler,
Browser,
Bundler { browser_only: bool },
Web,
NoModules { global: String },
Node { experimental_modules: bool },
}
@ -59,7 +59,7 @@ impl Bindgen {
Bindgen {
input: Input::None,
out_name: None,
mode: OutputMode::Bundler,
mode: OutputMode::Bundler { browser_only: false },
debug: false,
typescript: false,
demangle: true,
@ -93,7 +93,7 @@ impl Bindgen {
fn switch_mode(&mut self, mode: OutputMode, flag: &str) -> Result<(), Error> {
match self.mode {
OutputMode::Bundler => self.mode = mode,
OutputMode::Bundler { .. } => self.mode = mode,
_ => bail!(
"cannot specify `{}` with another output mode already specified",
flag
@ -126,9 +126,9 @@ impl Bindgen {
Ok(self)
}
pub fn browser(&mut self, browser: bool) -> Result<&mut Bindgen, Error> {
if browser {
self.switch_mode(OutputMode::Browser, "--browser")?;
pub fn web(&mut self, web: bool) -> Result<&mut Bindgen, Error> {
if web {
self.switch_mode(OutputMode::Web, "--web")?;
}
Ok(self)
}
@ -145,6 +145,16 @@ impl Bindgen {
Ok(self)
}
pub fn browser(&mut self, browser: bool) -> Result<&mut Bindgen, Error> {
if browser {
match &mut self.mode {
OutputMode::Bundler { browser_only } => *browser_only = true,
_ => bail!("cannot specify `--browser` with other output types"),
}
}
Ok(self)
}
pub fn no_modules_global(&mut self, name: &str) -> Result<&mut Bindgen, Error> {
match &mut self.mode {
OutputMode::NoModules { global } => *global = name.to_string(),
@ -661,15 +671,16 @@ impl OutputMode {
fn always_run_in_browser(&self) -> bool {
match self {
OutputMode::Browser => true,
OutputMode::Web => true,
OutputMode::NoModules { .. } => true,
OutputMode::Bundler { browser_only } => *browser_only,
_ => false,
}
}
fn browser(&self) -> bool {
fn web(&self) -> bool {
match self {
OutputMode::Browser => true,
OutputMode::Web => true,
_ => false,
}
}

View File

@ -108,7 +108,7 @@ fn rmain() -> Result<(), Error> {
let mut b = Bindgen::new();
b.debug(debug)
.nodejs(node)?
.browser(!node)?
.web(!node)?
.input_module(module, wasm)
.keep_debug(false)
.emit_start(false)

View File

@ -22,7 +22,8 @@ Options:
--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
--browser Generate output that only works in a browser
--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)
--no-modules-global VAR Name of the global variable to initialize
--typescript Output a TypeScript definition file (on by default)
@ -41,6 +42,7 @@ Options:
struct Args {
flag_nodejs: bool,
flag_browser: bool,
flag_web: bool,
flag_no_modules: bool,
flag_typescript: bool,
flag_no_typescript: bool,
@ -89,6 +91,7 @@ fn rmain(args: &Args) -> Result<(), Error> {
let mut b = Bindgen::new();
b.input_path(input)
.nodejs(args.flag_nodejs)?
.web(args.flag_web)?
.browser(args.flag_browser)?
.no_modules(args.flag_no_modules)?
.debug(args.flag_debug)

View File

@ -14,8 +14,8 @@ 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
`--browser`. The main difference here is how the shim JS and module are loaded,
where this example uses old-school `script` tags while `--browser` uses ES
`--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.
[wab]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler

View File

@ -7,8 +7,8 @@
<script src='pkg/without_a_bundler_no_modules.js'></script>
<script type=module>
// Like with the `--browser` output the exports are immediately available
// but they won't work until we initialize the module. Unlike `--browser`,
// 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.

View File

@ -11,7 +11,7 @@ $ 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 \
--browser
--web
```
and then opening `index.html` in a browser should run the example!

View File

@ -3,13 +3,13 @@
set -ex
# Note that typically we'd use `wasm-pack` to build the crate, but the
# `--browser` flag is very new to `wasm-bindgen` and as such doesn't have
# `--web` flag is very new to `wasm-bindgen` and as such doesn't have
# support in `wasm-pack` yet. Support will be added soon though!
cargo build --target wasm32-unknown-unknown --release
cargo run --manifest-path ../../crates/cli/Cargo.toml \
--bin wasm-bindgen -- \
../../target/wasm32-unknown-unknown/release/without_a_bundler.wasm --out-dir pkg \
--browser
--web
python3 -m http.server

View File

@ -4,15 +4,15 @@
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler
This example shows how the `--browser` flag can be used load code in a
This example shows how the `--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].
> **Note**: the `--browser` flag is quite new to `wasm-bindgen`, and does not
> **Note**: the `--web` flag is quite new to `wasm-bindgen`, and does not
> currently have support in `wasm-pack` yet. Support will be added soon though!
First let's take a look at the code and see how when we're using `--browser`
First let's take a look at the code and see how when we're using `--web`
we're not actually losing any functionality!
```rust
@ -40,7 +40,7 @@ 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`.
While similar to the newer `--browser`, the `--no-modules` flag has a few
While similar to the newer `--web`, the `--no-modules` flag has a few
caveats:
* It does not support [local JS snippets][snippets]

View File

@ -29,11 +29,17 @@ 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.
### `--browser`
For more information about this see the section on [deployment]
This flag will tailor the output specifically for browsers, making it
incompatible with Node. This will basically make the generated JS a tiny bit
smaller as runtime checks for Node won't be necessary.
[deployment]: deployment.html
### `--web`
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`
@ -44,8 +50,7 @@ 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.
More information can be found in the [documentation for building without
ECMAScript modules](./no-esm.html).
For more information about this see the section on [deployment]
### `--typescript`
@ -71,3 +76,9 @@ When post-processing the `.wasm` binary, do not demangle Rust symbols in the
When post-processing the `.wasm` binary, do not strip DWARF debug info custom
sections.
### `--browser`
When generating bundler-compatible code (see the section on [deployment]) this
indicates that the bundled code is always intended to go into a browser so a few
checks for Node.js can be elided.

View File

@ -29,17 +29,17 @@ necessary.
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
`--browser` flag. You can check out a [full example][nomex] in the
`--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 `--browser`.
* When using `wasm-bindgen` directly you'll pass `--web`.
* 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 `--browser` mode is not able to use NPM dependencies.
* The `--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 `--browser` is not supported in `wasm-pack` because it is
> **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
@ -48,7 +48,7 @@ documentation, but the highlights of this output are:
[browser requirements]: browser-support.html
The `wasm-bindgen` CLI also supports an output mode called `--no-modules` which
is similar to `--browser` in that it requires manual initialization of the wasm
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`.

View File

@ -64,7 +64,7 @@ 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 `--browser` and the default bundler output mode are supported. To support
* 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
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