Make WASM example

[schungx]

@alvinhochun do you think it is possible to make a "minimal" WASM example with simplest build pipeline?

I think that would be a great help to people who wants to embed Rhai into WASM.

If short enough, I can also put that example into the Book.

[alvinhochun]

I am sceptical. There are plenty of ways to set up a project that uses Rust and targets the web browser, but for most projects that make use of wasm-bindgen, adding Rhai is no different than what you would do for a native bin project.

IMO for a project which does something special on WASM, like a web framework or a game engine that handles HTML DOM events, then it would make a lot of sense to provide an example project setup for others to get started since they likely require some very specific initialization code. But Rhai is nothing like these; in theory one just needs to add the crate like any other normal library crates and calls its code.

Except there is just a tiny problem in practice -- the BasicTimePackage in Rhai requires Instant::now(). On WASM (wasm32-unknown-unknown) the only way to get this is to import it from the Web API. Currently Rhai uses https://github.com/sebcrozet/instant for this and assumes that the user is already using wasm-bindgen for its project. I would consider wasm-bindgen to be the de facto crate to use (let's just say stdweb is now defunct), but some people prefer to avoid it since it adds significant build time. When someone tries to use Rhai in a project that isn't using wasm-bindgen, weird things happen. Providing an example project does not really help in this case.

I would suggest a few alternative solutions:

• The lazy way: Document that Rhai requires wasm-bindgen and don't support any projects that doesn't use it.
  • Con: This doesn't actually help projects that are not using wasm-bindgen.
• Reduced functionality: Add a feature flag to disable BasicTimePackage and to remove the instant dependency.
  • Con: Don't we have too many feature flags already?
• Using transitive feature: Remove the wasm-bindgen feature flag on instant and instead require the user to specify the dependency's feature flags explicitly. This allows the user to choose whether to use wasm-bindgen or manually provide the required WASM extern fn in their custom JS glue code.
  • Pro: This should work for all use cases.
  • Con: This makes it slightly more inconvenient to users who uses wasm-bindgen.
  • Con: Users that are not very familiar with WASM may have trouble using it.

[schungx]

Ah. Makes perfect sense.

So, for your third solution, what if we add a wasm-bindgen feature to Rhai that turns on instant/wasm-bindgen? That should be useful in case in the future we have more things that requires special setup with wasm-bindgen...

In that case, maybe have a stdweb feature as well, just for completeness sake?

[alvinhochun]

Yes, that is the typical way to set feature flags transitively. Maybe it can also be added to the default features so that it won't cause too much trouble for users who already requires wasm-bindgen. We will need to document it and instruct users to disable default features if they don't want to use wasm-bindgen.

Using stdweb nowadays is really not a good idea anymore (see https://github.com/koute/stdweb/issues/403) so I would consider just skipping it, but there is no harm in providing the option, as long as we don't need to provide extra support.

[schungx]

Actually, in this case, just adding a wasm-bindgen feature would be fine. The docs can mention that a WASM build should include this feature, so there is no need to make a set of default features just for it.

[schungx]

Does instant work without wasm-bindgen? It looks like it does, because wasm-bindgen is a feature for it...

If it doesn't, then I probably need to disable instant when wasm-bindgen is not there...

[alvinhochun]

Does instant work without wasm-bindgen? It looks like it does, because wasm-bindgen is a feature for it...

It should work as long as the user provides the binding manually. I haven't actually tried it though.

[schungx]

Come to think of it, the instant dependency is hidden behind a target gate. I am not sure if it is possible to add a feature just for a particular target.

It might be simpler just to say it requires wasm-bindgen...