search

WebAssembly / binaryen

Optimizer and compiler/toolchain library for WebAssembly
Apache License 2.0
7.36k stars 721 forks source link

Add documentation for Binaryen as polyfill #290

Open data-ux opened 8 years ago

data-ux commented 8 years ago

I'm using wasm.js as a polyfill to run arbitrary wasm textual s-expression modules in current (non-wasm supporting) browsers. This is admittedly a very odd use case, but binaryen should have all the functionality needed to make it work.

The actual issue I'm struggling with is the lack of documentation of the wasm.js API and/or examples. This is my current attempt at using the wasm-js.cpp API from JS: https://gist.github.com/data-ux/230c97f2ae8c446d2eaecf7e61f43f7b

It mostly works, but linear memory access, using i64 types, grow_memory etc. throw exceptions, so clearly I'm missing something.

I'd be happy to contribute documentation on integrating wasm.js once I have wrapped my head around the subject.

kripken commented 8 years ago

Yes, wasm.js has a lot of integration with emscripten, that's what it's designed for. Things like i64 don't exist in JS, so it has special code for them, ditto for unaligned reads (which emscripten disallows because of how JS typed arrays work), etc. etc.

If you just want to interpret a standalone s-expr file, you should be able to just take the binaryen shell, and build that to JS. I can help out if you want. We could add an s-expr evaller .js to the project.

However: s-exprs are a temporary thing. We will have an official text format before the 1.0 launch of WebAssembly, and it will most likely be very different. Therefore I'm not sure of the value of making it easy for people to learn about s-exprs, if they will need to unlearn that later.

data-ux commented 8 years ago

Help with compiling the binaryen shell to JS would be appreciated. I think it would be even better if the evaller.js could be input with either binary or s-expession wasm modules. That way it would have broader applicability. I can contribute a wrapper JS that exposes the functionality, but I haven't done c++ development in 15 years, so I'm afraid I cannot be useful on that front.

To my understanding the AST semantics of MVP WebAssembly have stabilized and I'm assuming the eventual official text format will be a close textual representation of the AST (syntax details like parens or not might change etc.). Or do you foresee that it's possible the official text format will be a further departure, for example code would be presented in C-like syntax?

kripken commented 8 years ago

Yes, in fact most of the proposals (from months ago to more recently) that I've seen almost all involve a more C-like syntax with curly braces and so forth. So I would not be surprised to see that happen.

My inclination is it makes sense for wait for the text format to materialize before providing a sandbox for learning wasm using text. For binary, the issue is that the binary format is still changing quite a bit, e.g. from preorder to postorder around now, and more to come, so I think it's too early for that as well.

But I'm open to other thoughts on this, that's just my general feeling.

data-ux commented 8 years ago

Yeah, I found the text format discussion in the design repo. The most important use case for the text format is "view source" of modules distributed as binary. In my opinion a direct mapping of the AST to text would serve the use case best. Adding any kind of translation/sugar, like infix operators and the like, would only make it harder to reason about the underlying actual wasm code.

I'm hoping my wasm playground can inform the discussion about the official text format. I'm planning to add a couple of different rendering styles that users can choose from.

The evaller.js would be useful in any case.

kripken commented 8 years ago

Fair point about this informing discussion. I wrote a PR that adds webidl bindings which let you use binaryen from JS, see #312. That might already be enough for what you want, if not, we can add more bindings.

data-ux commented 8 years ago

Yeah, this is pretty much perfect. Great work. I have published my playground with the new binaryen.js as the WASM machinery: http://ast.run/.

Do the current bindings support calling exports with other types than f64? It also seems that exported functions can only return f64, too.

kripken commented 8 years ago

Nice site :)

Yeah, very limited so far - this was just enough to get basics working, to see its in the right direction. Would be nice if we added more to the IDL as necessary.