Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Docs] Add some Rust docs #14394

Closed
wants to merge 2 commits into from
Closed

[Docs] Add some Rust docs #14394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
842a789
[Rust] Add some Rust docs
kripken Jun 7, 2021
6373da2
typo
kripken Jun 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions site/source/docs/contributing/developers_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ automatically when you create a pull request, and they should all pass. If you
run into trouble with a test failure you can't fix, please let the developers
know.

.. _developers-guide-bisecting:

Bisecting
=========

Expand Down
51 changes: 51 additions & 0 deletions site/source/docs/porting/Rust.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
.. Rust:

=================
Rust + Emscripten
=================

The
`Rust programming language <https://www.rust-lang.org/>`_
has direct support for compiling to WebAssembly.
In addition to that, Rust can be used with Emscripten, which allows Rust to
benefit from Emscripten's API support. For example, using Emscripten with Rust
can allow you to port a Rust codebase using :ref:`OpenGL <OpenGL-support>` or
:ref:`Pthreads <Pthreads-support>`, as Emscripten has library support code for
those APIs which handles the large differences between them and the closest Web
APIs.

============
Installation
============

The Rust toolchain will look for ``emcc`` and the other Emscripten components
in the path. You should therefore first
:ref:`download, install, and add Emscripten to your path <sdk-download-and-install>`.

It is crucial to install the proper versions of the tools. Specifically, Rust
uses a particular LLVM version, and Emscripten must use the same one, so that
object files and so forth are all compatible.

As of June 2021, stable Rust is ``1.52.1``, which uses LLVM 12, which was
branched off of the ``llvmorg-12-init`` tag. That LLVM change rolled into
Emscripten in
`56b877afe7d1b651d6b9a2ba5d5df074876172ff <https://chromium.googlesource.com/emscripten-releases/+/56b877afe7d1b651d6b9a2ba5d5df074876172ff>`_,
RReverser marked this conversation as resolved.
Show resolved Hide resolved
which means that the compatible version of Emscripten can be installed as follows:

.. code-block:: bash

emsdk install 56b877afe7d1b651d6b9a2ba5d5df074876172ff
emsdk activate 56b877afe7d1b651d6b9a2ba5d5df074876172ff
Comment on lines +37 to +38
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be worth finding and documenting the first tagged Emscripten release after this point, IMO, rather than suggesting that users install an untagged release. A priori, I would expect that the risk of LLVM incompatibilities would be outweighed by the downsides of documenting an untagged git commit, namely that the commit is impossible to remember and raises questions about stability for users who do not know about our release process.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the hash of a roll, so it has passed the roller's full test suite. For that reason I don't think the risk is significantly higher than a release.

It worries me to allow several further rolls in between (which is what going to the next release would cause). It's not just LLVM incompatibilities, it's binaryen as well, where LLVM and binaryen overlap (say, on the binary format of a new feature).

I think the minimal possible distance in terms of commits, that is still fully tested, is safest.

Copy link
Collaborator

@RReverser RReverser Jun 7, 2021 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I understand, we can add arbitrary tags to hashes in emsdk pretty easily. Could we add a tag for this version like rust-1.52.1 or llvm-12 to make it easier to use & remember? At least until we automate this, it seems useful to have human-readable names.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it just needs a tag here? https://github.com/emscripten-core/emsdk/blob/main/emscripten-releases-tags.txt

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea! Yes, it is as simple as that.

+1 for adding both of those tags there, as both could be useful for people wanting to use emscripten with a provided LLVM.

We should also test them. Testing the LLVM one can be done with a PR in emscripten (that replaces the tot build with LLVM 12). For Rust, I'm not sure how best to do it, but one option might be to create an emscripten-core/rust repo and add some amount of testing there. Or perhaps the repo could be more generically named, as we may want multiple languages there eventually (e.g. Zig).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it is as simple as that.

(narrator voice) It wasn't as simple as that 😅 emscripten-core/emsdk#836


(For more on how to find the proper Emscripten hash for a particular LLVM
commit, see our
`release process docs <https://github.com/emscripten-core/emscripten/blob/main/docs/process.md#release-processes>`_
which are summarized in the
:ref:`developer's guide <developers-guide-bisecting>`.)
Comment on lines +40 to +44
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should be recommending these docs to end users, even parenthetically. We should make using Rust with Emscripten appear as simple as possible.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be happy to remove it to a lower section "for advanced users" or such? I do think there is value for the type of developer that does want to know how things work internally.


===========
Hello World
===========

TODO

1 change: 1 addition & 0 deletions site/source/docs/porting/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,5 +21,6 @@ The topics in this section cover the main integration points that you need to co
simd
exceptions
asyncify
Rust
../compiling/Building-Projects

2 changes: 1 addition & 1 deletion site/source/docs/porting/pthreads.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. Pthreads support:
.. _Pthreads-support:

==============================
Pthreads support
Expand Down