Skip to content

feat: reference types argument #888

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

feat: reference types argument #888

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 35 additions & 15 deletions docs/src/commands/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
5 changes: 5 additions & 0 deletions src/bindgen.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ pub fn wasm_bindgen_build(
out_dir: &Path,
out_name: &Option<String>,
disable_dts: bool,
reference_types: bool,
target: Target,
profile: BuildProfile,
) -> Result<(), failure::Error> {
Expand Down Expand Up @@ -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);
Expand Down
12 changes: 12 additions & 0 deletions src/command/build.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ pub struct Build {
pub crate_data: manifest::CrateData,
pub scope: Option<String>,
pub disable_dts: bool,
pub reference_types: bool,
pub target: Target,
pub profile: BuildProfile,
pub mode: InstallMode,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -370,6 +378,7 @@ impl Build {
&self.out_dir,
&self.out_name,
self.disable_dts,
self.reference_types,
self.target,
self.profile,
)?;
Expand All @@ -378,6 +387,9 @@ impl Build {
}

fn step_run_wasm_opt(&mut self) -> Result<(), Error> {
if self.reference_types {
return Ok(());
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should generate at least a debug message to notify the user that wasm-opt had been disabled.

}
let args = match self
.crate_data
.configured_profile(self.profile)
Expand Down
2 changes: 1 addition & 1 deletion src/command/test.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
)
}
Expand Down
12 changes: 12 additions & 0 deletions tests/all/build.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
2 changes: 1 addition & 1 deletion tests/all/test.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down