diff --git a/docs/src/commands/build.md b/docs/src/commands/build.md index fa9b7dd1..d5ba09b8 100644 --- a/docs/src/commands/build.md +++ b/docs/src/commands/build.md @@ -48,7 +48,6 @@ wasm-pack build --out-name index # index.d.ts index.js index_bg.d.ts index_bg.wasm package.json README.md ``` - ## Profile The `build` command accepts an optional profile argument: one of `--dev`, @@ -57,11 +56,11 @@ The `build` command accepts an optional profile argument: one of `--dev`, This controls whether debug assertions are enabled, debug info is generated, and which (if any) optimizations are enabled. -| Profile | Debug Assertions | Debug Info | Optimizations | Notes | -|---------------|------------------|------------|---------------|---------------------------------------| -| `--dev` | Yes | Yes | No | Useful for development and debugging. | +| Profile | Debug Assertions | Debug Info | Optimizations | Notes | +| ------------- | ---------------- | ---------- | ------------- | ----------------------------------------------------------- | +| `--dev` | Yes | Yes | No | Useful for development and debugging. | | `--profiling` | No | Yes | Yes | Useful when profiling and investigating performance issues. | -| `--release` | No | No | Yes | Useful for shipping to production. | +| `--release` | No | No | Yes | Useful for shipping to production. | The `--dev` profile will build the output package using cargo's [default non-release profile][cargo-profile-sections-documentation]. Building this way is @@ -85,12 +84,12 @@ using the compiled output][deploy]. wasm-pack build --target nodejs ``` -| Option | Usage | Description | -|-----------|------------|-----------------------------------------------------------------------------------------------------| -| *not specified* or `bundler` | [Bundler][bundlers] | Outputs JS that is suitable for interoperation with a Bundler like Webpack. You'll `import` the JS and the `module` key is specified in `package.json`. `sideEffects: false` is by default. | -| `nodejs` | [Node.js][deploy-nodejs] | Outputs JS that uses CommonJS modules, for use with a `require` statement. `main` key in `package.json`. | -| `web` | [Native in browser][deploy-web] | Outputs JS that can be natively imported as an ES module in a browser, but the WebAssembly must be manually instantiated and loaded. | -| `no-modules` | [Native in browser][deploy-web] | Same as `web`, except the JS is included on a page and modifies global state, and doesn't support as many `wasm-bindgen` features as `web` | +| Option | Usage | Description | +| ---------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _not specified_ or `bundler` | [Bundler][bundlers] | Outputs JS that is suitable for interoperation with a Bundler like Webpack. You'll `import` the JS and the `module` key is specified in `package.json`. `sideEffects: false` is by default. | +| `nodejs` | [Node.js][deploy-nodejs] | Outputs JS that uses CommonJS modules, for use with a `require` statement. `main` key in `package.json`. | +| `web` | [Native in browser][deploy-web] | Outputs JS that can be natively imported as an ES module in a browser, but the WebAssembly must be manually instantiated and loaded. | +| `no-modules` | [Native in browser][deploy-web] | Same as `web`, except the JS is included on a page and modifies global state, and doesn't support as many `wasm-bindgen` features as `web` | [deploy]: https://rustwasm.github.io/docs/wasm-bindgen/reference/deployment.html [bundlers]: https://rustwasm.github.io/docs/wasm-bindgen/reference/deployment.html#bundlers @@ -116,14 +115,35 @@ the npm documentation [here][npm-scope-documentation]. ## Mode The `build` command accepts an optional `--mode` argument. + ``` wasm-pack build examples/js-hello-world --mode no-install ``` -| Option | Description | -|---------------|------------------------------------------------------------------------------------------| -| `no-install` | `wasm-pack init` implicitly and create wasm binding without installing `wasm-bindgen`. | -| `normal` | do all the stuffs of `no-install` with installed `wasm-bindgen`. | +| Option | Description | +| ------------ | -------------------------------------------------------------------------------------- | +| `no-install` | `wasm-pack init` implicitly and create wasm binding without installing `wasm-bindgen`. | +| `normal` | do all the stuffs of `no-install` with installed `wasm-bindgen`. | + +## Support for Reference Types + +You can enable support for reference types with the optional `--reference-types` argument. + +``` +wasm-pack build examples/js-hello-world --reference-types +``` + +This feature is hoped to enable more efficient communication between the host (JS) and the wasm module, but not yet all browsers support it. + +For more information about reference types, you should read the [wasm-bindgen Guide](https://rustwasm.github.io/docs/wasm-bindgen/reference/reference-types.html#support-for-reference-types). + +This argument will automatically disable `wasm-opt`. +Otherwise compilation would crash with the following error: + +``` +[parse exception: Only 1 table definition allowed in MVP (at 0:4234)] +Fatal: error in parsing input +``` ## Extra options diff --git a/src/bindgen.rs b/src/bindgen.rs index 02d02dce..f5bb32f7 100644 --- a/src/bindgen.rs +++ b/src/bindgen.rs @@ -17,6 +17,7 @@ pub fn wasm_bindgen_build( out_dir: &Path, out_name: &Option, disable_dts: bool, + reference_types: bool, target: Target, profile: BuildProfile, ) -> Result<(), failure::Error> { @@ -48,6 +49,10 @@ pub fn wasm_bindgen_build( .arg(out_dir) .arg(dts_arg); + if reference_types { + cmd.arg("--reference-types"); + } + let target_arg = build_target_arg(target, &bindgen_path)?; if supports_dash_dash_target(bindgen_path.to_path_buf())? { cmd.arg("--target").arg(target_arg); diff --git a/src/command/build.rs b/src/command/build.rs index b1b6eb50..a3dff59e 100644 --- a/src/command/build.rs +++ b/src/command/build.rs @@ -27,6 +27,7 @@ pub struct Build { pub crate_data: manifest::CrateData, pub scope: Option, pub disable_dts: bool, + pub reference_types: bool, pub target: Target, pub profile: BuildProfile, pub mode: InstallMode, @@ -119,6 +120,11 @@ pub struct BuildOptions { /// this flag will disable generating this TypeScript file. pub disable_dts: bool, + #[structopt(long = "reference-types")] + /// Enable support for reference types. This feature is hoped to enable more efficient + /// communication between the host (JS) and the wasm module, but not yet all browsers support it. + pub reference_types: bool, + #[structopt(long = "target", short = "t", default_value = "bundler")] /// Sets the target environment. [possible values: bundler, nodejs, web, no-modules] pub target: Target, @@ -160,6 +166,7 @@ impl Default for BuildOptions { scope: None, mode: InstallMode::default(), disable_dts: false, + reference_types: false, target: Target::default(), debug: false, dev: false, @@ -196,6 +203,7 @@ impl Build { crate_data, scope: build_opts.scope, disable_dts: build_opts.disable_dts, + reference_types: build_opts.reference_types, target: build_opts.target, profile, mode: build_opts.mode, @@ -370,6 +378,7 @@ impl Build { &self.out_dir, &self.out_name, self.disable_dts, + self.reference_types, self.target, self.profile, )?; @@ -378,6 +387,9 @@ impl Build { } fn step_run_wasm_opt(&mut self) -> Result<(), Error> { + if self.reference_types { + return Ok(()); + } let args = match self .crate_data .configured_profile(self.profile) diff --git a/src/command/test.rs b/src/command/test.rs index 9c5ab9b1..b693dd5f 100644 --- a/src/command/test.rs +++ b/src/command/test.rs @@ -294,7 +294,7 @@ impl Test { bail!( "Ensure that you have \"{}\" as a dependency in your Cargo.toml file:\n\ [dev-dependencies]\n\ - wasm-bindgen-test = \"0.2\"", + wasm-bindgen-test = \"0.3\"", style("wasm-bindgen-test").bold().dim(), ) } diff --git a/tests/all/build.rs b/tests/all/build.rs index 0c59ba85..a887e82f 100644 --- a/tests/all/build.rs +++ b/tests/all/build.rs @@ -376,3 +376,15 @@ fn build_crates_with_same_names() { .assert() .success(); } + +#[test] +fn build_with_reftypes() { + let fixture = utils::fixture::js_hello_world(); + fixture.install_local_wasm_bindgen(); + fixture + .wasm_pack() + .arg("build") + .arg("--reference-types") + .assert() + .success(); +} diff --git a/tests/all/test.rs b/tests/all/test.rs index bc95e8d6..f5920c04 100644 --- a/tests/all/test.rs +++ b/tests/all/test.rs @@ -197,7 +197,7 @@ fn complains_about_missing_wasm_bindgen_test_dependency() { "Ensure that you have \"wasm-bindgen-test\" as a dependency in your Cargo.toml file", )) .stderr(predicates::str::contains("[dev-dependencies]")) - .stderr(predicates::str::contains("wasm-bindgen-test = \"0.2\"")); + .stderr(predicates::str::contains("wasm-bindgen-test = \"0.3\"")); } #[test]