1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2# Rust Wasm Bindgen 3 4* [rust_wasm_bindgen_dependencies](#rust_wasm_bindgen_dependencies) 5* [rust_wasm_bindgen_register_toolchains](#rust_wasm_bindgen_register_toolchains) 6* [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain) 7* [rust_wasm_bindgen](#rust_wasm_bindgen) 8* [RustWasmBindgenInfo](#RustWasmBindgenInfo) 9 10 11## Overview 12 13Bazel rules for generating wasm modules for Javascript using [wasm-bindgen][wb]. 14 15## Setup 16 17To begin using the `wasm-bindgen` rules, users can load the necessary dependencies 18in their workspace by adding the following to their `WORKSPACE.bazel` file. 19 20```starlark 21load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_dependencies", "rust_wasm_bindgen_register_toolchains") 22 23rust_wasm_bindgen_dependencies() 24 25rust_wasm_bindgen_register_toolchains() 26``` 27 28This should enable users to start using the [rust_wasm_bindgen](#rust_wasm_bindgen) 29rule. However, it's common to want to control the version of `wasm-bindgen` in the 30workspace instead of relying on the one provided by `rules_rust`. In this case, users 31should avoid calling `rust_wasm_bindgen_register_toolchains` and instead use the 32[rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain) rule to define their own 33toolchains to register in the workspace. 34 35### Interfacing with Javascript rules 36 37While it's recommended for users to mantain their own , in the 38`@rules_rust//wasm_bindgen` package there exists interface sub-packages for various 39Javascript Bazel rules. E.g. `build_bazel_rules_nodejs` or `aspect_rules_js`. The 40rules defined there are a more convenient way to use `rust_wasm_bindgen` with the 41associated javascript rules due to the inclusion of additional providers. Each 42directory contains a `defs.bzl` file that defines the different variants of 43`rust_wasm_bindgen`. (e.g. `nodejs_rust_wasm_bindgen` for the `rules_nodejs` submodule). 44 45 46[wb]: https://github.com/rustwasm/wasm-bindgen 47 48 49<a id="rust_wasm_bindgen"></a> 50 51## rust_wasm_bindgen 52 53<pre> 54rust_wasm_bindgen(<a href="#rust_wasm_bindgen-name">name</a>, <a href="#rust_wasm_bindgen-bindgen_flags">bindgen_flags</a>, <a href="#rust_wasm_bindgen-target">target</a>, <a href="#rust_wasm_bindgen-wasm_file">wasm_file</a>) 55</pre> 56 57Generates javascript and typescript bindings for a webassembly module using [wasm-bindgen][ws]. 58 59[ws]: https://rustwasm.github.io/docs/wasm-bindgen/ 60 61An example of this rule in use can be seen at [@rules_rust//examples/wasm](../examples/wasm) 62 63**ATTRIBUTES** 64 65 66| Name | Description | Type | Mandatory | Default | 67| :------------- | :------------- | :------------- | :------------- | :------------- | 68| <a id="rust_wasm_bindgen-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 69| <a id="rust_wasm_bindgen-bindgen_flags"></a>bindgen_flags | Flags to pass directly to the bindgen executable. See https://github.com/rustwasm/wasm-bindgen/ for details. | List of strings | optional | `[]` | 70| <a id="rust_wasm_bindgen-target"></a>target | The type of output to generate. See https://rustwasm.github.io/wasm-bindgen/reference/deployment.html for details. | String | optional | `"bundler"` | 71| <a id="rust_wasm_bindgen-wasm_file"></a>wasm_file | The `.wasm` file or crate to generate bindings for. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 72 73 74<a id="rust_wasm_bindgen_toolchain"></a> 75 76## rust_wasm_bindgen_toolchain 77 78<pre> 79rust_wasm_bindgen_toolchain(<a href="#rust_wasm_bindgen_toolchain-name">name</a>, <a href="#rust_wasm_bindgen_toolchain-bindgen">bindgen</a>) 80</pre> 81 82The tools required for the `rust_wasm_bindgen` rule. 83 84In cases where users want to control or change the version of `wasm-bindgen` used by [rust_wasm_bindgen](#rust_wasm_bindgen), 85a unique toolchain can be created as in the example below: 86 87```python 88load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain") 89 90rust_bindgen_toolchain( 91 bindgen = "//3rdparty/crates:wasm_bindgen_cli__bin", 92) 93 94toolchain( 95 name = "wasm_bindgen_toolchain", 96 toolchain = "wasm_bindgen_toolchain_impl", 97 toolchain_type = "@rules_rust//wasm_bindgen:toolchain_type", 98) 99``` 100 101Now that you have your own toolchain, you need to register it by 102inserting the following statement in your `WORKSPACE` file: 103 104```python 105register_toolchains("//my/toolchains:wasm_bindgen_toolchain") 106``` 107 108For additional information, see the [Bazel toolchains documentation][toolchains]. 109 110[toolchains]: https://docs.bazel.build/versions/master/toolchains.html 111 112**ATTRIBUTES** 113 114 115| Name | Description | Type | Mandatory | Default | 116| :------------- | :------------- | :------------- | :------------- | :------------- | 117| <a id="rust_wasm_bindgen_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 118| <a id="rust_wasm_bindgen_toolchain-bindgen"></a>bindgen | The label of a `wasm-bindgen-cli` executable. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 119 120 121<a id="RustWasmBindgenInfo"></a> 122 123## RustWasmBindgenInfo 124 125<pre> 126RustWasmBindgenInfo(<a href="#RustWasmBindgenInfo-js">js</a>, <a href="#RustWasmBindgenInfo-ts">ts</a>, <a href="#RustWasmBindgenInfo-wasm">wasm</a>) 127</pre> 128 129Info about wasm-bindgen outputs. 130 131**FIELDS** 132 133 134| Name | Description | 135| :------------- | :------------- | 136| <a id="RustWasmBindgenInfo-js"></a>js | Depset[File]: The Javascript files produced by `wasm-bindgen`. | 137| <a id="RustWasmBindgenInfo-ts"></a>ts | Depset[File]: The Typescript files produced by `wasm-bindgen`. | 138| <a id="RustWasmBindgenInfo-wasm"></a>wasm | File: The `.wasm` file generated by `wasm-bindgen`. | 139 140 141<a id="rust_wasm_bindgen_dependencies"></a> 142 143## rust_wasm_bindgen_dependencies 144 145<pre> 146rust_wasm_bindgen_dependencies() 147</pre> 148 149Declare dependencies needed for the `rules_rust` [wasm-bindgen][wb] rules. 150 151[wb]: https://github.com/rustwasm/wasm-bindgen 152 153 154 155**RETURNS** 156 157list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories 158 defined by this macro. 159 160 161<a id="rust_wasm_bindgen_register_toolchains"></a> 162 163## rust_wasm_bindgen_register_toolchains 164 165<pre> 166rust_wasm_bindgen_register_toolchains(<a href="#rust_wasm_bindgen_register_toolchains-register_toolchains">register_toolchains</a>) 167</pre> 168 169Registers the default toolchains for the `rules_rust` [wasm-bindgen][wb] rules. 170 171[wb]: https://github.com/rustwasm/wasm-bindgen 172 173 174**PARAMETERS** 175 176 177| Name | Description | Default Value | 178| :------------- | :------------- | :------------- | 179| <a id="rust_wasm_bindgen_register_toolchains-register_toolchains"></a>register_toolchains | Whether or not to register toolchains. | `True` | 180 181 182