Replace target flags with --target

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`.

crates/cli-support/src/js/mod.rs

@@ -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
+    /// `--target no-modules`, `--target web`, or for bundlers. This is the very
-    /// performed in `finalize`.
+    /// 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
+            // In `--target no-modules` mode we need to both expose a name on
-            // global object as well as generate our own custom start function.
+            // 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
+            // expose the same initialization function as `--target no-modules`
-            // default export of the module.
+            // 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
+        // First up, imports don't work at all in `--target no-modules` mode as
-        // not sure how to import them.
+        // 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`; \
+                    "local JS snippets are not supported with `--target no-modules`; \
-                     use `--web` or no flag instead",
+                     use `--target web` or no flag instead",
                 );
             }
             if let decode::ImportModule::Named(module) = &import.module {
                 bail!(
-                    "import from `{}` module not allowed with `--no-modules`; \
+                    "import from `{}` module not allowed with `--target no-modules`; \
-                     use `--nodejs`, `--web`, or no flag instead",
+                     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
+        // Similar to `--target no-modules`, only allow vendor prefixes
-        // apis, shouldn't be necessary for things like npm packages or other
+        // basically for web apis, shouldn't be necessary for things like npm
-        // imported items.
+        // 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);

crates/cli-support/src/lib.rs

@@ -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)
     }

crates/cli/src/bin/wasm-bindgen.rs

@@ -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
+    --target TARGET              What type of output to generate, valid
-    --web                        Generate output that only works in a browser
+                                 values are [web, bundler, nodejs, no-modules],
-    --browser                    Hint that JS should only be compatible with a browser
+                                 and the default is [bundler]
-    --no-modules                 Generate output that only works in a browser (without modules)
     --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)?

examples/raytrace-parallel/build.sh

@@ -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

examples/without-a-bundler-no-modules/README.md

@@ -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
+which performs a similar purpose except it uses `--target no-modules` instead of
-`--web`. The main difference here is how the shim JS and module are loaded,
+`--target web`. The main difference here is how the shim JS and module are
-where this example uses old-school `script` tags while `--web` uses ES
+loaded, where this example uses old-school `script` tags while `--target web`
-modules.
+uses ES modules.
 
 [wab]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler

examples/without-a-bundler-no-modules/index.html

@@ -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
+      // Like with the `--target web` output the exports are immediately
-      // but they won't work until we initialize the module. Unlike `--web`,
+      // available but they won't work until we initialize the module. Unlike
-      // however, the globals are all stored on a `wasm_bindgen` global. The
+      // `--target web`, however, the globals are all stored on a
-      // global itself is the initialization function and then the properties of
+      // `wasm_bindgen` global. The global itself is the initialization
-      // the global are all the exported functions.
+      // 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

examples/without-a-bundler/README.md

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

guide/src/examples/without-a-bundler.md

@@ -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
+`--target no-modules` flag to the `wasm-bindgen` CLI.
-no-modules` in `wasm-pack`.
 
-While similar to the newer `--web`, the `--no-modules` flag has a few
+While similar to the newer `--target web`, the `--target no-modules` flag has a
-caveats:
+few caveats:
 
 * It does not support [local JS snippets][snippets]
 * It does not generate an ES module

guide/src/reference/cli.md

@@ -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
+This flag indicates what flavor of output what `wasm-bindgen` should generate.
-usage of `require` of the generated JS and internally using `require` instead of
+For example it could generate code to be loaded in a bundler like Webpack, a
-ECMAScript modules. When using this flag no further postprocessing (aka a
+native web page, or Node.js. For a full list of options to pass this flag, see
-bundler) should be necessary to work with the wasm.
+the section on [deployment]
-
-For more information about this 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.
+When `--target no-modules` is used this flag can indicate what the name of the
-The generated JS shims are an ES module which export a `default` instantiation
+global to assign generated bindings to.
-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.
 
 For more information about this see the section on [deployment]
 

guide/src/reference/deployment.md

@@ -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
+**`--target bundler`**
-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
+The default output of `wasm-bindgen`, or the `bundler` target, assumes a model
-output of `wasm-bindgen` you will need a bundler of some form.
+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
+The CLI also supports an output mode called `--target no-modules` which is
-is similar to `--web` in that it requires manual initialization of the wasm
+similar to the `web` target in that it requires manual initialization of the
-and is intended to be included in web pages without any further postprocessing.
+wasm and is intended to be included in web pages without any further
-See the [without a bundler example][nomex] for some more information about
+postprocessing.  See the [without a bundler example][nomex] for some more
-`--no-modules`, which corresponds to `--target no-modules` in `wasm-pack`.
+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/

guide/src/reference/js-snippets.md

@@ -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
+* Only `--target web` and the default bundler output mode are supported. To
-  `--nodejs` we'd need to translate ES module syntax to CommonJS (this is
+  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
+  `--target no-modules` we'd have to similarly translate from ES modules to
-  else.
+  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

src/lib.rs

@@ -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)]