The default wasm-bindgen toolchain can now optionally be registered (#640)

UebelAndre · web-flow · commit 920256900c36 · 2021-03-22T17:49:55.000Z
I find it to be the common case that users will want to register their own `rust_wasm_bindgen_toolchain` since they'll be writing code with their own set of crate dependencies and would otherwise be limited to the version of `wasm-bindgen` used in the default toolchain. This PR should make it clearer and easier for users looking to setup their own toolchain.

Notable changes in this PR:
- Added `register_default_toolchain` to `rust_wasm_bindgen_repositories`
- Improved docs
- Raised the default version of `rules_nodejs` from `3.1.0` to `3.2.2` to pick up a few bug fixes.
- Added a `providers.bzl` file for easy access to what `rust_wasm_bindgen` returns
diff --git a/docs/flatten.md b/docs/flatten.md
@@ -1149,7 +1149,9 @@ Generates a toolchain-bearing repository that declares the toolchains from some
 rust_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-wasm_file">wasm_file</a>)
 </pre>
 
-Generates javascript and typescript bindings for a webassembly module.
+Generates javascript and typescript bindings for a webassembly module using [wasm-bindgen][ws].
+
+[ws]: https://rustwasm.github.io/docs/wasm-bindgen/
 
 To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
 external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):
@@ -1160,7 +1162,9 @@ load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositori
 rust_wasm_bindgen_repositories()
 ```
 
-An example of this rule in use can be seen at [@rules_rust//examples/wasm/...](../examples/wasm)
+For more details on `rust_wasm_bindgen_repositories`, see [here](#rust_wasm_bindgen_repositories).
+
+An example of this rule in use can be seen at [@rules_rust//examples/wasm](../examples/wasm)
 
 
 **ATTRIBUTES**
@@ -1183,18 +1187,19 @@ rust_wasm_bindgen_toolchain(<a href="#rust_wasm_bindgen_toolchain-name">name</a>
 
 The tools required for the `rust_wasm_bindgen` rule.
 
-You can also use your own version of wasm-bindgen using the toolchain rules below:
+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 = "//my/raze:cargo_bin_wasm_bindgen",
+    bindgen = "//my/cargo_raze:cargo_bin_wasm_bindgen",
 )
 
 toolchain(
-    name = "wasm-bindgen-toolchain",
-    toolchain = "wasm-bindgen-toolchain-impl",
+    name = "wasm_bindgen_toolchain",
+    toolchain = "wasm_bindgen_toolchain_impl",
     toolchain_type = "@rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
 )
 ```
@@ -1203,10 +1208,12 @@ 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")
+register_toolchains("//my/toolchains:wasm_bindgen_toolchain")
 ```
 
-For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+For additional information, see the [Bazel toolchains documentation][toolchains].
+
+[toolchains]: https://docs.bazel.build/versions/master/toolchains.html
 
 
 **ATTRIBUTES**
@@ -1215,7 +1222,7 @@ For additional information, see the [Bazel toolchains documentation](https://doc
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_wasm_bindgen_toolchain-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| <a id="rust_wasm_bindgen_toolchain-bindgen"></a>bindgen |  The label of a <code>wasm-bindgen</code> executable.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="rust_wasm_bindgen_toolchain-bindgen"></a>bindgen |  The label of a <code>wasm-bindgen-cli</code> executable.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 
 
 <a id="#cargo_build_script"></a>
@@ -1426,12 +1433,16 @@ N.B. A "proxy repository" is needed to allow for registering the toolchain (with
 ## rust_wasm_bindgen_repositories
 
 <pre>
-rust_wasm_bindgen_repositories()
+rust_wasm_bindgen_repositories(<a href="#rust_wasm_bindgen_repositories-register_default_toolchain">register_default_toolchain</a>)
 </pre>
 
-Declare dependencies needed for wasm-bindgen.
+Declare dependencies needed for [rust_wasm_bindgen](#rust_wasm_bindgen).
+
+**PARAMETERS**
 
-This macro will load crate dependencies of `wasm-bindgen` that are generated using [cargo raze][raze] inside the rules_rust     repository. This makes the default toolchain `@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain` available. For     more information on `wasm_bindgen` toolchains, see [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain).
 
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="rust_wasm_bindgen_repositories-register_default_toolchain"></a>register_default_toolchain |  If True, the default [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain)     (<code>@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain</code>) is registered. This toolchain requires a set of dependencies     that were generated using [cargo raze](https://github.com/google/cargo-raze). These will also be loaded.   |  <code>True</code> |
 
 
diff --git a/docs/rust_wasm_bindgen.md b/docs/rust_wasm_bindgen.md
@@ -11,7 +11,9 @@
 rust_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-wasm_file">wasm_file</a>)
 </pre>
 
-Generates javascript and typescript bindings for a webassembly module.
+Generates javascript and typescript bindings for a webassembly module using [wasm-bindgen][ws].
+
+[ws]: https://rustwasm.github.io/docs/wasm-bindgen/
 
 To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
 external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):
@@ -22,7 +24,9 @@ load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositori
 rust_wasm_bindgen_repositories()
 ```
 
-An example of this rule in use can be seen at [@rules_rust//examples/wasm/...](../examples/wasm)
+For more details on `rust_wasm_bindgen_repositories`, see [here](#rust_wasm_bindgen_repositories).
+
+An example of this rule in use can be seen at [@rules_rust//examples/wasm](../examples/wasm)
 
 
 **ATTRIBUTES**
@@ -45,18 +49,19 @@ rust_wasm_bindgen_toolchain(<a href="#rust_wasm_bindgen_toolchain-name">name</a>
 
 The tools required for the `rust_wasm_bindgen` rule.
 
-You can also use your own version of wasm-bindgen using the toolchain rules below:
+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 = "//my/raze:cargo_bin_wasm_bindgen",
+    bindgen = "//my/cargo_raze:cargo_bin_wasm_bindgen",
 )
 
 toolchain(
-    name = "wasm-bindgen-toolchain",
-    toolchain = "wasm-bindgen-toolchain-impl",
+    name = "wasm_bindgen_toolchain",
+    toolchain = "wasm_bindgen_toolchain_impl",
     toolchain_type = "@rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
 )
 ```
@@ -65,10 +70,12 @@ 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")
+register_toolchains("//my/toolchains:wasm_bindgen_toolchain")
 ```
 
-For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+For additional information, see the [Bazel toolchains documentation][toolchains].
+
+[toolchains]: https://docs.bazel.build/versions/master/toolchains.html
 
 
 **ATTRIBUTES**
@@ -77,20 +84,24 @@ For additional information, see the [Bazel toolchains documentation](https://doc
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_wasm_bindgen_toolchain-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| <a id="rust_wasm_bindgen_toolchain-bindgen"></a>bindgen |  The label of a <code>wasm-bindgen</code> executable.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="rust_wasm_bindgen_toolchain-bindgen"></a>bindgen |  The label of a <code>wasm-bindgen-cli</code> executable.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
 
 
 <a id="#rust_wasm_bindgen_repositories"></a>
 
 ## rust_wasm_bindgen_repositories
 
 <pre>
-rust_wasm_bindgen_repositories()
+rust_wasm_bindgen_repositories(<a href="#rust_wasm_bindgen_repositories-register_default_toolchain">register_default_toolchain</a>)
 </pre>
 
-Declare dependencies needed for wasm-bindgen.
+Declare dependencies needed for [rust_wasm_bindgen](#rust_wasm_bindgen).
+
+**PARAMETERS**
 
-This macro will load crate dependencies of `wasm-bindgen` that are generated using [cargo raze][raze] inside the rules_rust     repository. This makes the default toolchain `@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain` available. For     more information on `wasm_bindgen` toolchains, see [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain).
 
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="rust_wasm_bindgen_repositories-register_default_toolchain"></a>register_default_toolchain |  If True, the default [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain)     (<code>@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain</code>) is registered. This toolchain requires a set of dependencies     that were generated using [cargo raze](https://github.com/google/cargo-raze). These will also be loaded.   |  <code>True</code> |
 
 
diff --git a/wasm_bindgen/BUILD.bazel b/wasm_bindgen/BUILD.bazel
diff --git a/wasm_bindgen/providers.bzl b/wasm_bindgen/providers.bzl
@@ -0,0 +1,17 @@
+"""A module for re-exporting the providers used by the rust_wasm_bindgen rule"""
+
+load(
+    "@build_bazel_rules_nodejs//internal/providers:declaration_info.bzl",
+    _DeclarationInfo = "DeclarationInfo",
+)
+load(
+    "@build_bazel_rules_nodejs//internal/providers:js_providers.bzl",
+    _JSEcmaScriptModuleInfo = "JSEcmaScriptModuleInfo",
+    _JSModuleInfo = "JSModuleInfo",
+    _JSNamedModuleInfo = "JSNamedModuleInfo",
+)
+
+DeclarationInfo = _DeclarationInfo
+JSEcmaScriptModuleInfo = _JSEcmaScriptModuleInfo
+JSModuleInfo = _JSModuleInfo
+JSNamedModuleInfo = _JSNamedModuleInfo
diff --git a/wasm_bindgen/repositories.bzl b/wasm_bindgen/repositories.bzl
@@ -18,21 +18,23 @@ load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
 load("//wasm_bindgen/raze:crates.bzl", "rules_rust_wasm_bindgen_fetch_remote_crates")
 
 # buildifier: disable=unnamed-macro
-def rust_wasm_bindgen_repositories():
-    """Declare dependencies needed for wasm-bindgen.
+def rust_wasm_bindgen_repositories(register_default_toolchain = True):
+    """Declare dependencies needed for [rust_wasm_bindgen](#rust_wasm_bindgen).
 
-    This macro will load crate dependencies of `wasm-bindgen` that are generated using [cargo raze][raze] inside the rules_rust \
-    repository. This makes the default toolchain `@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain` available. For \
-    more information on `wasm_bindgen` toolchains, see [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain).
+    Args:
+        register_default_toolchain (Label, optional): If True, the default [rust_wasm_bindgen_toolchain](#rust_wasm_bindgen_toolchain)
+            (`@rules_rust//wasm_bindgen:default_wasm_bindgen_toolchain`) is registered. This toolchain requires a set of dependencies
+            that were generated using [cargo raze](https://github.com/google/cargo-raze). These will also be loaded.
     """
 
     maybe(
         http_archive,
         name = "build_bazel_rules_nodejs",
-        sha256 = "dd4dc46066e2ce034cba0c81aa3e862b27e8e8d95871f567359f7a534cccb666",
-        urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/3.1.0/rules_nodejs-3.1.0.tar.gz"],
+        sha256 = "55a25a762fcf9c9b88ab54436581e671bc9f4f523cb5a1bd32459ebec7be68a8",
+        urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/3.2.2/rules_nodejs-3.2.2.tar.gz"],
     )
 
-    rules_rust_wasm_bindgen_fetch_remote_crates()
-
-    native.register_toolchains(str(Label("//wasm_bindgen:default_wasm_bindgen_toolchain")))
+    # Load dependencies of the default toolchain and register it.
+    if register_default_toolchain:
+        rules_rust_wasm_bindgen_fetch_remote_crates()
+        native.register_toolchains(str(Label("//wasm_bindgen:default_wasm_bindgen_toolchain")))
diff --git a/wasm_bindgen/wasm_bindgen.bzl b/wasm_bindgen/wasm_bindgen.bzl
@@ -13,19 +13,20 @@
 # limitations under the License.
 
 # buildifier: disable=module-docstring
-load("@build_bazel_rules_nodejs//internal/providers:declaration_info.bzl", "DeclarationInfo")
+# buildifier: disable=bzl-visibility
+load("//rust/private:transitions.bzl", "wasm_bindgen_transition")
 load(
-    "@build_bazel_rules_nodejs//internal/providers:js_providers.bzl",
+    ":providers.bzl",
+    "DeclarationInfo",
     "JSEcmaScriptModuleInfo",
     "JSModuleInfo",
     "JSNamedModuleInfo",
 )
 
-# buildifier: disable=bzl-visibility
-load("//rust/private:transitions.bzl", "wasm_bindgen_transition")
-
 _WASM_BINDGEN_DOC = """\
-Generates javascript and typescript bindings for a webassembly module.
+Generates javascript and typescript bindings for a webassembly module using [wasm-bindgen][ws].
+
+[ws]: https://rustwasm.github.io/docs/wasm-bindgen/
 
 To use the Rust WebAssembly bindgen rules, add the following to your `WORKSPACE` file to add the
 external repositories for the Rust bindgen toolchain (in addition to the Rust rules setup):
@@ -36,24 +37,27 @@ load("@rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositori
 rust_wasm_bindgen_repositories()
 ```
 
-An example of this rule in use can be seen at [@rules_rust//examples/wasm/...](../examples/wasm)
+For more details on `rust_wasm_bindgen_repositories`, see [here](#rust_wasm_bindgen_repositories).
+
+An example of this rule in use can be seen at [@rules_rust//examples/wasm](../examples/wasm)
 """
 
 _WASM_BINDGEN_TOOLCHAIN_DOC = """\
 The tools required for the `rust_wasm_bindgen` rule.
 
-You can also use your own version of wasm-bindgen using the toolchain rules below:
+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 = "//my/raze:cargo_bin_wasm_bindgen",
+    bindgen = "//my/cargo_raze:cargo_bin_wasm_bindgen",
 )
 
 toolchain(
-    name = "wasm-bindgen-toolchain",
-    toolchain = "wasm-bindgen-toolchain-impl",
+    name = "wasm_bindgen_toolchain",
+    toolchain = "wasm_bindgen_toolchain_impl",
     toolchain_type = "@rules_rust//wasm_bindgen:wasm_bindgen_toolchain",
 )
 ```
@@ -62,10 +66,12 @@ 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")
+register_toolchains("//my/toolchains:wasm_bindgen_toolchain")
 ```
 
-For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
+For additional information, see the [Bazel toolchains documentation][toolchains].
+
+[toolchains]: https://docs.bazel.build/versions/master/toolchains.html
 """
 
 def _rust_wasm_bindgen_impl(ctx):
@@ -175,7 +181,7 @@ rust_wasm_bindgen_toolchain = rule(
     doc = _WASM_BINDGEN_TOOLCHAIN_DOC,
     attrs = {
         "bindgen": attr.label(
-            doc = "The label of a `wasm-bindgen` executable.",
+            doc = "The label of a `wasm-bindgen-cli` executable.",
             executable = True,
             cfg = "exec",
         ),
