☂️ Document Dart's support for compilation to Wasm

[parlough]

Support:

• Update the platform target discussion on the Dart overview page
  • https://dart.dev/overview#platform (image and text)
  • https://dart.dev/overview#web-platform
• Indicate supported browser versions, potentially distinguished from JS
  • https://dart.dev/resources/faq#web-execution
  • Elsewhere?
• Clarify somewhere that WASI and non-web platforms are not yet supported
• Check web FAQ entries to see if they could use an update

Semantics and behavior:

• Update 'Numbers in Dart' and elsewhere to account for dart2wasm supporting native semantics #5345
• Verify all mentions of different semantics on web clarify if that is for JS, Wasm, or both

Interop:

• ☂️ JS/web static interop overview, docs, and tutorials #5438
• Verify all interop documentation accounts for Wasm and its differences
• Document support for interaction between Wasm code.

Command line tools:

• Document dart compile wasm command #5440
• Document how webdev supports Wasm compilation
  • Blocked by missing build_web_compilers support ([webdev] Generate auto-switching combined build for dart2js and dart2wasm output webdev#2296)
  • https://dart.dev/tools/webdev
• Update the web deployment docs for Wasm
  • Discuss optimization levels and options, their meanings, etc
  • Mention how to enable automatic switching between JS and Wasm

Tooling:

• Update DevTools table for support from tooling for the Wasm target and distinguish from JS
  • https://dart.dev/tools/dart-devtools
• Update web debugging docs for what's supported (or not) for Wasm vs JS
  • https://dart.dev/web/debugging

[parlough]

For readers note that this list is tentative and still being added to and adjusted! Also not all of these entries need to be resolved as this is just a rough list.

@MaryaBelanger I created this as a place to start collecting pieces that might need additions or changes as we start to work on Wasm docs over time. Feel free to edit this as you complete your evaluation process - Thanks :)

@kevmoo Also feel free to add to the issue or comment here with anything that comes to you as important or relevant :D

[kevmoo]

Also need to figure out if this is webdev thing or build_web_compilers (I think it's BWC)

[MaryaBelanger]

Sound list! Couple extra things I'm wondering about from my evaluation:

1. It seems like we need a dedicated "Wasm" page somewhere on dart.dev.

   It could catch the few bits of information on this list that need to go somewhere, plus serve as a landing page for "wasm" in general. It could also cover the points made in ☂️ Help Dart developers navigate Dart's platform interop support #5475's Wasm section:

   • Explain Wasm support status and limitations
   • Clarify support is for compiling to Wasm, not running
   • Document how to interop with web/JS
   • Add examples for interacting with Dart from Wasm source

   I know there's some aversion to presenting Wasm as a singular topic for Dart though, so maybe a dedicated page is a bad idea? Then all the points that aren't already updates to existing pages would have to be distributed across existing pages as well.

   Q: If there were a Wasm landing page, where would it appropriate? Under Development>Web apps, or its own page under Interop, or under Interop>Javascript interop?

2. Example migration walkthrough.

   I'm not sure if this belongs more on flutter.dev, but, like having a dedicated Wasm landing page, it'd be good to have a dedicated Wasm migration page/section too. Migrating to wasm is just js interop and package:web migration, which we already have docs for. Wasm migration would just be a repeat / amalgamation of that info.

   I think a good way to do this that isn't too much of a repeat of the existing js/web docs would be walking through a real, reasonably complex package migration example that we've already done.

   It could show enabling wasm tests, the feedback on what doesn't work, and then the simple web migration stuff, followed by more complex js_interop stuff dealing maybe with async / binary data / numbers.

[parlough]

It seems like we need a dedicated "Wasm" page somewhere on dart.dev...I know there's some aversion to presenting Wasm as a singular topic for Dart though.

I think in the short term it could make sense to have its own page to have a clearly identifiable home for those wanting to learn about the new deployment target, its status, how to prepare for it, how to enable it, how to test it, etc. It'll likely be easier for us to maintain while there's still a lot of evolution too.

However, you're right and in the long term it likely doesn't make sense to document it as a standalone entity. The experimental/migration period is of course a bit special though, so it's probably fine. Eventually I can see it being a section of the web deployment page with links to other relevant docs. Later on we can redirect it to a section on the deployment page or wherever we decide later on down the road :)

Q: If there were a Wasm landing page, where would it appropriate? Under Development>Web apps, or its own page under Interop, or under Interop>Javascript interop?

As for where that could be located, I think your suggestion of it being under Development > Web apps makes perfect sense. I imagine a redirect like dart.dev/go/wasm might end up being the most popular entry point anyway.

Migrating to wasm is just js interop and package:web migration, which we already have docs for. Wasm migration would just be a repeat / amalgamation of that info.

That's true. As mentioned in our last chat, I think we can expand those docs with a section about trying to compile to Wasm to verify those steps have been completed successfully.

I think a good way to do this...would be walking through a real, reasonably complex package migration example that we've already done...

I love that idea!! As you mentioned, the existing JS interop docs will cover most necessary code changes. So that leaves tooling and workflow changes, which a walkthrough of a package migration including tests and everything seems like it could perfectly showcase that. We might have to end up crafting an example, but that shouldn't be too bad. The number and other semantics differences can of course be sprinkled in as well :)

[MaryaBelanger]

Thanks for the feedback @parlough! I'll add the more concrete ideas we settled on to the top description.

Another thought: In addition to updating the web deployment page, we should probably update the "Build a web app" page too.... Would that update fall under "updating for wasm"? Or is that more of just a package:web update?

I was thinking maybe this simple example from mit might be a good sample web app to reframe that rewrite around, if that makes sense: dart-lang/sdk#32894 (comment)

[mit-mit]

I stubbed out some content here that may be useful input into this docs effort: main...wasm