# Rust Wasm Bindgen
* [rust_wasm_bindgen_dependencies](#rust_wasm_bindgen_dependencies)
* [rust_wasm_bindgen_register_toolchains](#rust_wasm_bindgen_register_toolchains)
* [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain)
* [rust_wasm_bindgen](#rust_wasm_bindgen)
* [RustWasmBindgenInfo](#RustWasmBindgenInfo)
## Overview
Bazel rules for generating wasm modules for Javascript using [wasm-bindgen][wb].
## Setup
To begin using the `wasm-bindgen` rules, users can load the necessary dependencies
in their workspace by adding the following to their `WORKSPACE.bazel` file.
```starlark
load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_dependencies", "rust_wasm_bindgen_register_toolchains")
rust_wasm_bindgen_dependencies()
rust_wasm_bindgen_register_toolchains()
```
This should enable users to start using the [rust_wasm_bindgen](#rust_wasm_bindgen)
rule. However, it's common to want to control the version of `wasm-bindgen` in the
workspace instead of relying on the one provided by `rules_rust`. In this case, users
should avoid calling `rust_wasm_bindgen_register_toolchains` and instead use the
[rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain) rule to define their own
toolchains to register in the workspace.
### Interfacing with Javascript rules
While it's recommended for users to mantain their own , in the
`@rules_rust//wasm_bindgen` package there exists interface sub-packages for various
Javascript Bazel rules. E.g. `build_bazel_rules_nodejs` or `aspect_rules_js`. The
rules defined there are a more convenient way to use `rust_wasm_bindgen` with the
associated javascript rules due to the inclusion of additional providers. Each
directory contains a `defs.bzl` file that defines the different variants of
`rust_wasm_bindgen`. (e.g. `nodejs_rust_wasm_bindgen` for the `rules_nodejs` submodule).
[wb]: https://github.com/rustwasm/wasm-bindgen
## rust_wasm_bindgen
rust_wasm_bindgen(name, bindgen_flags, target, wasm_file)
Generates javascript and typescript bindings for a webassembly module using [wasm-bindgen][ws].
[ws]: https://rustwasm.github.io/docs/wasm-bindgen/
An example of this rule in use can be seen at [@rules_rust//examples/wasm](../examples/wasm)
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| bindgen_flags | Flags to pass directly to the bindgen executable. See https://github.com/rustwasm/wasm-bindgen/ for details. | List of strings | optional | `[]` |
| target | The type of output to generate. See https://rustwasm.github.io/wasm-bindgen/reference/deployment.html for details. | String | optional | `"bundler"` |
| wasm_file | The `.wasm` file or crate to generate bindings for. | Label | required | |
## rust_wasm_bindgen_toolchain
rust_wasm_bindgen_toolchain(name, bindgen)
The tools required for the `rust_wasm_bindgen` rule.
In cases where users want to control or change the version of `wasm-bindgen` used by [rust_wasm_bindgen](#rust_wasm_bindgen),
a unique toolchain can be created as in the example below:
```python
load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
rust_bindgen_toolchain(
bindgen = "//3rdparty/crates:wasm_bindgen_cli__bin",
)
toolchain(
name = "wasm_bindgen_toolchain",
toolchain = "wasm_bindgen_toolchain_impl",
toolchain_type = "@rules_rust//wasm_bindgen:toolchain_type",
)
```
Now that you have your own toolchain, you need to register it by
inserting the following statement in your `WORKSPACE` file:
```python
register_toolchains("//my/toolchains:wasm_bindgen_toolchain")
```
For additional information, see the [Bazel toolchains documentation][toolchains].
[toolchains]: https://docs.bazel.build/versions/master/toolchains.html
**ATTRIBUTES**
| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
| name | A unique name for this target. | Name | required | |
| bindgen | The label of a `wasm-bindgen-cli` executable. | Label | optional | `None` |
## RustWasmBindgenInfo
RustWasmBindgenInfo(js, ts, wasm)
Info about wasm-bindgen outputs.
**FIELDS**
| Name | Description |
| :------------- | :------------- |
| js | Depset[File]: The Javascript files produced by `wasm-bindgen`. |
| ts | Depset[File]: The Typescript files produced by `wasm-bindgen`. |
| wasm | File: The `.wasm` file generated by `wasm-bindgen`. |
## rust_wasm_bindgen_dependencies
rust_wasm_bindgen_dependencies()
Declare dependencies needed for the `rules_rust` [wasm-bindgen][wb] rules.
[wb]: https://github.com/rustwasm/wasm-bindgen
**RETURNS**
list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories
defined by this macro.
## rust_wasm_bindgen_register_toolchains
rust_wasm_bindgen_register_toolchains(register_toolchains)
Registers the default toolchains for the `rules_rust` [wasm-bindgen][wb] rules.
[wb]: https://github.com/rustwasm/wasm-bindgen
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| register_toolchains | Whether or not to register toolchains. | `True` |