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`.
rustwasm · Mar 21, 2019 · 995be7c · 995be7c
1 parent 93cab3d
commit 995be7c
Show file tree

Hide file tree

Showing 12 changed files with 125 additions and 118 deletions.
diff --git a/crates/cli-support/src/js/mod.rs b/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
-    /// 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);

diff --git a/crates/cli-support/src/lib.rs b/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)
     }

diff --git a/crates/cli/src/bin/wasm-bindgen.rs b/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
-    --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)?

diff --git a/examples/raytrace-parallel/build.sh b/examples/raytrace-parallel/build.sh
diff --git a/examples/without-a-bundler-no-modules/README.md b/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
-`--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
diff --git a/examples/without-a-bundler-no-modules/index.html b/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
-      // 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

diff --git a/examples/without-a-bundler/README.md b/examples/without-a-bundler/README.md
@@ -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!
diff --git a/guide/src/examples/without-a-bundler.md b/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
-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

diff --git a/guide/src/reference/cli.md b/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
-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`
-
-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`).
+### `--no-modules-global VAR`
 
-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]