wasm-bindgen-cli installation: misguiged by the doc

[MaciekTalaska]

Installation steps for wasm-bindgen-cli are not clear

I have some experience with Rust, but I am very new to the WASM (just started recently) and I have bumped on some problems at the very beginning. I wanted to compile samples downloaded from GitHub, but I was unable to do so due to the fact that I struggled with installing wasm-bindgen command-line tool.

Steps to Reproduce

1. Go to https://rustwasm.github.io/docs/wasm-bindgen/reference/cli.html - This section describes how to install wasm-bindgen
2. Install wasm-pack as described on the page mentioned above
3. invoke wasm-pack build (as stated in the docs)
4. Try to invoke wasm-bindgen in the command line - that fails, due to the fact that wasm-bindgen is not a part of the wasm-pack

Expected Behavior

I think going step by step by step through the Installation section (https://rustwasm.github.io/docs/wasm-bindgen/reference/cli.html) should result in:

• wasm-pack being installed and available as a command-line tool
• wasm-bindgen being installed and available to invoke from the command line

I suggest that the section describing the installation of the wasm-bindgen command-line tool should be altered, for example:

The recommend way to install the wasm-pack command line tool is with the wasm-pack installer described here. After installing wasm-pack, run the following commad to have wasm-bindgen installed: cargo install wasm-bindgen-cli

The following section of the doc is unclear to me:

Although the command line tool is available through its own crate, wasm-bindgen-cli, wasm-pack build will ensure the version installed matches the version of wasm-bindgen in Cargo.lock.)

Is this a leftover? Was wasm-pack responsible for installing wasm-bindgen-cli in the past? Could anyone clarify on this, please?

Actual Behavior

A the moment it is unclear what to do to have wasm-bindgen installed. One may figure out that there is additional crate wasm-bindgen-cli but I think it should be clearly mentioned what to do to have this utility installed.

I was not able to compile some of the samples downloaded from Github which required wasm-bindgen tool available as part of the build.

Additional Context

I think this could possibly be a showstopper for newcomers to the world of WASM in Rust (especially those not having experience with Rust itself).

I am happy to improve the documentation with the PR - if you accept th general direction of the changes (I mean: if I have not misunderstood something here)

[Pauan]

@MaciekTalaska You shouldn't install or use the wasm-bindgen CLI tool.

You should only be using wasm-pack (or one of the plugins, like the Webpack plugin or the Rollup plugin).

It is only necessary to run wasm-pack build, nothing else.

Is this a leftover? Was wasm-pack responsible for installing wasm-bindgen-cli in the past?

It is correct. wasm-pack is the tool that you should be using, it installs, manages, and runs wasm-bindgen for you, so you don't have to.

I was not able to compile some of the samples downloaded from Github which required wasm-bindgen tool available as part of the build.

Our examples all use wasm-pack, so if you find any samples which aren't using wasm-pack then they are wrong and they need to be changed to use wasm-pack.

I am happy to improve the documentation with the PR - if you accept th general direction of the changes (I mean: if I have not misunderstood something here)

We would gladly accept any contributions, if you can figure out a way to explain things more clearly.

[MaciekTalaska]

@Pauan

Thank you for your prompt response! I am a bit confused though.

It is only necessary to run wasm-pack build, nothing else.

This is what confuses me a lot. I have found that many examples of WASM apps written in Rust which require wasm-bindgen to be built. Many yew examples require wasm-bindgen

It is correct. wasm-pack is the tool that you should be using, it installs, manages, and runs wasm-bindgen for you, so you don't have to.

I really struggled to figure out why it works differently on my machine.

I have made some investigation on this (with the help of my friend) and it seem that the statement in the docs is true, i.e. wasm-bindgen is installed after wasm-pack. The strange thing is this tool is installed in a very strange place (~/.config/.wasm-pack/wsm-bindgen-<some_numbers_here> on my machine). This makes it (wasm-bindgen) unavailable for invoking from the command-line, even though it is installed.

Is there any reason why wasm-bindgen is not available for the end-user to be invoked?

The current situation may lead to the situation of having 2 (possibly different) versions of wasm-bindgen-cli installed: one that is managed by wasm-pack, and the other one by the cargo itself.

I am afraid this may result in some hard to track problems.

We would gladly accept any contributions if you can figure out a way to explain things more clearly.

I am more than happy to help to improve the docs, but the first step for me is to understand if this is something that is not working on my machine or I have misunderstood

My current understanding is:

1. wasm-bindgen is used internally by the wasm-pack itself. wasm-pack (as stated in the docs) installs and manages wasm-bindgen.
2. the way wasm-bindgen is installed (at the moment) prevents end-user from invoking it directly (well... you have to know the - pretty obscure - path, which could change with never versions).

This means that it is a bit inconvenient to use wasm-bindgen directly at the moment. The best solution probably is to have wasm-bindgen-cli installed side by side.

Taking all that (what I have written above) under consideration, I suggest to enhance the following part of the "Installation" doc on wasm-bindgen:

The recommend way to install the wasm-bindgen command line tool is with the wasm-pack installer described here. After installing wasm-pack, run wasm-pack build to install the command-line tool.

I think the following should be added:

Wasm-bindgen installed by wasm-pack is not directly available. It is used solely by the wasm-pack as a part of the build process.

Additional info should be added to answer the question:

What should I do if I need to invoke wasm-bindgen directly? (This is the case of compiling yew examples - as I have mentioned above).

What would you suggest here? Should the user install wasm-bindgen-cli directly? Or should such a person use wam-bindgen installed by wasm-pack (bu mind that this is going to be inconvenient, and build scripts may require some tinkering)

[Pauan]

I have found that many examples of WASM apps written in Rust which require wasm-bindgen to be built.

There's various reasons for that, it's partly because those examples are old and outdated. Another reason is that there is a lot of misinformation about wasm-pack. And another reason is that some people like to be as "bare metal" as they can, so they use as few tools as possible.

But the official stance is that wasm-pack should pretty much always be used instead of wasm-bindgen-cli.

Many yew examples require wasm-bindgen

Yes, that is a known issue. Yew should use wasm-pack instead.

The strange thing is this tool is installed in a very strange place (~/.config/.wasm-pack/wsm-bindgen-<some_numbers_here> on my machine). This makes it (wasm-bindgen) unavailable for invoking from the command-line, even though it is installed.

Yes, that's correct.

Is there any reason why wasm-bindgen is not available for the end-user to be invoked?

Because wasm-pack installs and uses multiple versions of wasm-bindgen simultaneously. There isn't a single version that could be used for wasm-bindgen.

This is because it's very important that the version of wasm-bindgen-cli exactly matches with your Cargo.lock. That synchronization is one of the things that wasm-pack does.

And you should not be running wasm-bindgen manually. It is an implementation detail, you should be using wasm-pack.

The current situation may lead to the situation of having 2 (possibly different) versions of wasm-bindgen-cli installed: one that is managed by wasm-pack, and the other one by the cargo itself.

Yes, but why is that a problem? It is intentional that there can (and should) be multiple versions of wasm-bindgen installed simultaneously. The multiple installations do not conflict with each other.

I am afraid this may result in some hard to track problems.

If you use wasm-pack, then there will be no problems, because wasm-pack manages everything for you.

If you don't use wasm-pack, then yes you will have problems, but not because of the multiple versions. Instead you will have problems with the version of wasm-bindgen-cli being out of sync (which wasm-pack solves).

What would you suggest here? Should the user install wasm-bindgen-cli directly?

The best solution is for yew to change the examples to use wasm-pack.

The second best solution is for the end user to use wasm-pack and ignore the yew build script (the yew build scripts are not needed with wasm-pack).

The third best solution is for the end user to do cargo install wasm-bindgen-cli. This is really not recommended, but it is okay as a last resort. In that case you will have to manually manage the version yourself.

[MaciekTalaska]

@Pauan

Thank you for such a detailed explanation! I have the feeling that now I finally understand the relation between wasm-pack and wasm-bindgen and the reason why wasm-bindgen should not be used directly by the user.

I think most of what you wrote in your last comment should be included in the docs in the section describing the installation process of the wasm-bindgen command-line tool.

I suggest to add the following to the docs, so it is clear for others starting their journey with WASM and wasm-pack (especially that you have stated in your comments that there is a lot of misinformation about wasm-pack):

It is not recommended to install wasm-bindgen-cli as its version must match exactly the version of wasm-bindgen that is specified in the project's cargo.lock file. Using wasm-pack for building simplifies the build process as wasm-pack ensures that the proper version of wasm-bindgen command-line tool is used. That means that wasm-pack may install many different versions of wasm-bindgen, but will always make sure to use the correct one.

Note: if, for any reason, you decide to use wasm-bindgen directly (this is not recommended!) you will have to manually take care of using exactly the same version of wasm-bindgen command-line tool (wasm-bindgen-cli) that matches the version of wasm-bingden in cargo.lock.

If you think the above enhancement is ok, I am happy to create a PR for the review.

As for your suggestions regarding yew and its examples - I will try to improve yew's build script so that it uses wasm-pack for all the examples.

[MaciekTalaska]

as the relevant branch has been merged it is safe to close this (I hope it is ok if I do so).

[virtualritz]

The problem still persists. I read https://rustwasm.github.io/wasm-bindgen/reference/cli.html which I found after some googling. All in all I spent >20mins to find out that I have to cargo install wasm-bindgen-cli (after finding out, also through google, that there is a wasm-bingen-cli package).
There are no instructions on how to install a package that yields the wasm-bindgen executable anywhere – unless I just needed to google another 10mins and I would have found them ... ;)

And as others pointed out: many projects do require wasm-bindgen use. In my case because of rustwasm/wasm-pack#734 (I was just trying to build the tour example from https://github.com/hecrj/iced/tree/master/web).

[chinoto]

I did some dissection of wasm-pack to figure out what exactly it does, if this information were presented somewhere (in a more formal manner than I've written), I'm sure it would clear up a lot of confusion for people who prefer to understand what their tools are doing.
At one point before the dissection, I thought wasm-pack was written in JavaScript, but it turned out that the npm package was merely for installing/running a precompiled version of wasm-pack.