rules_rust_wasm_bindgen

Bazel rules for generating wasm modules for Javascript using wasm-bindgen.

Rules

rust_wasm_bindgen
rust_wasm_bindgen_toolchain

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.

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 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 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. 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. js_rust_wasm_bindgen for the rules_js submodule).

rust_wasm_bindgen

load("@rules_rust_wasm_bindgen//:defs.bzl", "rust_wasm_bindgen")

rust_wasm_bindgen(name, bindgen_flags, out_name, target, target_arch, wasm_file)

Generates javascript and typescript bindings for a webassembly module using wasm-bindgen.

An example of this rule in use can be seen at @rules_rust//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 wasm-bindgen executable. See https://github.com/rustwasm/wasm-bindgen/ for details.	List of strings	optional	`[]`
out_name	Set a custom output filename (Without extension. Defaults to target name).	String	optional	`""`
target	The type of output to generate. See https://rustwasm.github.io/wasm-bindgen/reference/deployment.html for details.	String	optional	`"bundler"`
target_arch	The target architecture to use for the wasm-bindgen command line option.	String	optional	`"wasm32"`
wasm_file	The `.wasm` crate to generate bindings for.	Label	required

rust_wasm_bindgen_test

load("@rules_rust_wasm_bindgen//:defs.bzl", "rust_wasm_bindgen_test")

rust_wasm_bindgen_test(name, deps, data, aliases, compile_data, crate_features, edition, env,
                       env_inherit, proc_macro_deps, rustc_env, rustc_env_files, rustc_flags,
                       target_arch, version, wasm)

Rules for running wasm-bindgen tests.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	List of other libraries to be linked to this library target. These can be either other `rust_library` targets or `cc_library` targets if linking a native library.	List of labels	optional	`[]`
data	List of files used by this rule at compile time and runtime. If including data at compile time with include_str!() and similar, prefer `compile_data` over `data`, to prevent the data also being included in the runfiles.	List of labels	optional	`[]`
aliases	Remap crates to a new name or moniker for linkage to this target These are other `rust_library` targets and will be presented as the new name given.	Dictionary: Label -> String	optional	`{}`
compile_data	List of files used by this rule at compile time. This attribute can be used to specify any data files that are embedded into the library, such as via the `include_str!` macro.	List of labels	optional	`[]`
crate_features	List of features to enable for this crate. Features are defined in the code using the `#[cfg(feature = "foo")]` configuration option. The features listed here will be passed to `rustc` with `--cfg feature="${feature_name}"` flags.	List of strings	optional	`[]`
edition	The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.	String	optional	`""`
env	Specifies additional environment variables to set when the test is executed by bazel test. Values are subject to `$(rootpath)`, `$(execpath)`, location, and "Make variable" substitution.	Dictionary: String -> String	optional	`{}`
env_inherit	Specifies additional environment variables to inherit from the external environment when the test is executed by bazel test.	List of strings	optional	`[]`
proc_macro_deps	List of `rust_proc_macro` targets used to help build this library target.	List of labels	optional	`[]`
rustc_env	Dictionary of additional `"key": "value"` environment variables to set for rustc. rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.	Dictionary: String -> String	optional	`{}`
rustc_env_files	Files containing additional environment variables to set for rustc. These files should contain a single variable per line, of format `NAME=value`, and newlines may be included in a value by ending a line with a trailing back-slash (`\\`). The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged. Note that the variables here are subject to workspace status stamping should the `stamp` attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. `NAME={WORKSPACE_STATUS_VARIABLE}`.	List of labels	optional	`[]`
rustc_flags	List of compiler flags passed to `rustc`. These strings are subject to Make variable expansion for predefined source/output path variables like `$location`, `$execpath`, and `$rootpath`. This expansion is useful if you wish to pass a generated file of arguments to rustc: `@$(location //package:target)`.	List of strings	optional	`[]`
target_arch	The target architecture to use for the wasm-bindgen command line option.	String	optional	`"wasm32"`
version	A version to inject in the cargo environment variable.	String	optional	`"0.0.0"`
wasm	The wasm target to test.	Label	required

rust_wasm_bindgen_toolchain

load("@rules_rust_wasm_bindgen//:defs.bzl", "rust_wasm_bindgen_toolchain")

rust_wasm_bindgen_toolchain(name, browser, browser_type, wasm_bindgen_cli, wasm_bindgen_test,
                            wasm_bindgen_test_runner, webdriver, webdriver_args, webdriver_json)

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, a unique toolchain can be created as in the example below:

load("@rules_rust_wasm_bindgen//:defs.bzl", "rust_wasm_bindgen_toolchain")

rust_wasm_bindgen_toolchain(
    wasm_bindgen_cli = "//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:

register_toolchains("//my/toolchains:wasm_bindgen_toolchain")

For additional information, see the Bazel toolchains documentation.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
browser	The browser entrypoint.	Label	optional	`None`
browser_type	The type of browser provided.	String	optional	`""`
wasm_bindgen_cli	The label of a `wasm-bindgen-cli` executable.	Label	optional	`None`
wasm_bindgen_test	The label of a `wasm-bindgen-test` crate.	Label	optional	`None`
wasm_bindgen_test_runner	The label of a `wasm-bindgen-test-runner` binary.	Label	optional	`None`
webdriver	The webdriver to use.	Label	optional	`None`
webdriver_args	Arguments to pass to the `webdriver` binary.	List of strings	optional	`[]`
webdriver_json	The `webdriver.json` config file for wasm-bindgen-test.	Label	optional	`None`

RustWasmBindgenInfo

load("@rules_rust_wasm_bindgen//:defs.bzl", "RustWasmBindgenInfo")

RustWasmBindgenInfo(js, root, snippets, ts, wasm)

Info about wasm-bindgen outputs.

FIELDS

Name	Description
js	Depset[File]: The Javascript files produced by `wasm-bindgen`.
root	str: The path to the root of the `wasm-bindgen --out-dir` directory.
snippets	File: The snippets directory produced by `wasm-bindgen`.
ts	Depset[File]: The Typescript files produced by `wasm-bindgen`.
wasm	File: The `.wasm` file generated by `wasm-bindgen`.