Documentation on using Emscripten targets

[tlively]

Although most community focus for Web projects is on using the wasm32-unknown-unknown target, wasm-bindgen, and wasm-pack to integrate Rust into traditional Web development, the Emscripten targets are still useful for other Web use cases. For example, when compiling full applications that use OpenGL, SDL, file system support, etc. Emscripten can do all of the heavy lifting to achieve portability between the desktop and the Web.

Unfortunately, getting everything set up right to successfully use Rust and Emscripten is a bit tricky and the requirements are not documented anywhere. The best documentation I know of is this blog post by @therocode. However, that blog post is harder to discover than I would like it to be, so I would like to add a section to this book covering the basics of using Rust and Emscripten together and linking to that blog post.

I have a couple questions about this:

1. Is this book a good place for Rust+Emscripten documentation to live? An alternative location would be the Emscripten website, but IMO it makes more sense to have these docs in a Rust-centric location because that better reflects the dependency the wasm32-unknown-emscripten Rust target has on Emscripten.

2. How should Rust+Emscripten docs be integrated into the existing book? They don't seem to fit into any existing sections, so it seems like adding a new section at the end and just a mention in the introduction might be the best way to go.

I look forward to hearing the community's thoughts! cc @RReverser

[ashleygwilliams]

Hey @tlively -

This group is largely inactive at this point. It'd be my recommendation to not add the emscripten toolchain to this book for a few reasons:

1. No one is actively maintaining this book, so this is not a great choice. We should reactivate maintenance on it but right now we aren't there.
2. No one is actively maintaining the story around how we talk about Rust and Wasm and so making a call like this doesn't really have a good set of folks to do that.

As for next steps pushing this forward, there are a few! (All hope is not lost!!) I think if you and/or @RReverser wanted to help reignite the rustwasm working group and then as members of the group wanted to work to expand the scope of our docs and presence that'd be a great start. I'd be happy to help to the extent I can. We should probably also talk to @alexcrichton and @fitzgen who are still active on wasm-bindgen and a few other tools in this GitHub org.

Let me know what you think! (Also, this is just my personal suggestion, I am a core member of this (defunct) group but by no means am I a sole decision maker.)

[tlively]

Thanks, @ashleygwilliams! I share your concerns about lack of maintenance here.

No one is actively maintaining this book, so this is not a great choice.

Do you know of a better choice in the Rust ecosystem? Also, I would happy to be add and maintain the Rust+Emscripten documentation in this book even if the rest of the book isn't being actively maintained. If the lack of overall maintenance means that no one is empowered and willing to approve that kind of addition, then I guess that wouldn't be an option, though.

I think if you and/or @RReverser wanted to help reignite the rustwasm working group and then as members of the group wanted to work to expand the scope of our docs and presence that'd be a great start.

I would love to be able to do this, but like for yourself and others, it would be hard for me to make time for that kind of undertaking. I'll need talk with my team about whether we should be doing more in the Rust space (cc @kripken).

[ashleygwilliams]

@tlively in the days following this convo, i've started kickstarting an attempt to revive maintainers for wasm-pack and in doing so have found some folks who are also interested in helping with documentation. i think it may be possible that we will have a group, though it may be in a few weeks. would you be ok putting this on hold until that happens?

timeline wise, i'm trying to get a kickoff call this week and then i imagine a week or so of auditing and planning before folks start diving into things. this seems like a issue to tackle after some of the issue triage and other things are addressed.

[tlively]

Sounds great! I'm happy to put this on hold while things get rolling again. Hopefully in the meantime anyone looking here for documentation will be able to find the blog post containing the current documentation.

[alexcrichton]

To answer some of the original questions, I think that emscripten may not be a great fit for the book. The book is mainly centered around wasm-bindgen and wasm-pack right now, going through the game of life and then configuring various aspects of it. While it's possible to do that with the emscripten target I get the impression that's not the main draw of emscripten. For example when covering emscripten you'd want to cover the graphics support, C integration support, etc.
Additionally many of the optimization techniques and/or tools mentioned in the book may have a different equivalent with emscripten or just not work at all with emscripten.

Basically for underlying technical reasons I think that the docs may want to live in a fairly separate location rather than all-in-one place. Although to the degree that this book is a landing page for all Rust-and-wasm users it definitely makes sense to include. I don't think this is as much of a gateway as it once was, but whatever the "main gateway" is for rust-and-wasm we'd certainly want to at the very least link all the emscripten documentation there.

[tlively]

That makes sense. Looking around a bit more, I found the docs landing page on the website. Perhaps that would be a more appropriate place since it seems to be more of a main gateway? Still happy to wait and see what new documentation initiatives might be kicked off, though.

[ashleygwilliams]

i do think that we've been, historically at least, interested in making a better "landing page" for rust wasm in a general sense. there was some work done around it... at this point at least a year ago... but i think it'd still be useful. especially because the ecosystem is much wider than just the work that is the purview of this group, and it would be useful to have a page that aided folks in discovering that.

[fitzgen]

I agree that the rustwasm organization isn't the right place or people to maintain Emscripten documentation. Emscripten experts are the right people to maintain it, and being integrated with the rest of the Emscripten documentation is probably where it will be most useful. However, I do think that it would make sense to add a new page to the reference section of the rustwasm book that essentially explains very briefly in a sentence or two why you might choose the Emscripten target and then links to the Emscripten documentation.

[RReverser]

However, I do think that it would make sense to add a new page to the reference section of the rustwasm book that essentially explains very briefly in a sentence or two why you might choose the Emscripten target and then links to the Emscripten documentation.

I agree that at least doing this makes sense. After all, newcomers to Rust + WebAssembly might not be familiar with wasm-bindgen vs Emscripten specifics and distinction.

At least right now, https://rustwasm.github.io/ as well as https://rustwasm.github.io/docs.html positions itself as a general "Rust and WebAssembly documentation". This likely sets expectations for beginners to be able to find all information about using Rust with WebAssembly at the same portal. As such, it would be useful to document different ways and toolchains in the same place, or at least make them easily and equally discoverable.

[tlively]

I would characterize the missing docs as Rust documentation more than Emscripten documentation, since they would cover things like Cargo configuration and commands. In particular, the tools the user invokes directly are all Rust tools like Cargo and rustc, so I would expect them to look in the Rust ecosystem for usage guides. I certainly agree that all documentation on Emscripten options and features should stay in the Emscripten organization and just be linked to from the Rust docs, though.

[ashleygwilliams]

whether owned by this working group or not, i think it's in the best interest of the Rust/Wasm story to have a generic landing page that can also help folks discover the Emscripten toolchain as well as other parts of the ecosystem. as it stands the current page is a good landing page for the wasmbindgen/pack toolchain, but that is one of many at this point. if ya'll could help out, i'd be happy to try to generate that page with ya'll., but we probably will need to sort how it is maintained

[tlively]

I would be happy to maintain any docs for Rust's Emscripten targets no matter where they end up living.