search

dart-lang / site-www

The source for the Dart website.
https://dart.dev
Other
970 stars 704 forks source link

☂️ Document Dart's support for compilation to Wasm #5609

Open parlough opened 9 months ago

parlough commented 9 months ago

Support:

Semantics and behavior:

Interop:

Command line tools:

Tooling:

parlough commented 9 months ago

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 commented 9 months ago

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

MaryaBelanger commented 9 months ago

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 #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 commented 9 months ago

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 commented 8 months ago

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: https://github.com/dart-lang/sdk/issues/32894#issuecomment-1855633728

mit-mit commented 7 months ago

I stubbed out some content here that may be useful input into this docs effort: https://github.com/dart-lang/site-www/compare/main...wasm