diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 50 |
1 files changed, 42 insertions, 8 deletions
@@ -4,7 +4,7 @@ Binaryen is a compiler and toolchain infrastructure library for WebAssembly, wri * **Parse** and **emit** WebAssembly, supporting the current S-Expression format. * **Interpret** WebAssembly. The interpreter passes 100% of the spec test suite. - * **Compile** asm.js to WebAssembly, which together with [Emscripten](http://emscripten.org), gives you a complete compiler toolchain from C and C++ to WebAssembly (Emscripten compiles C and C++ to asm.js, Binaryen compiles that to WebAssembly). + * **Compile** asm.js to WebAssembly, which together with [Emscripten](http://emscripten.org) which compiles C and C++ to asm.js, gives you a complete compiler toolchain from C and C++ to WebAssembly. This passes all of the relevant part of Emscripten's test suite (everything but some odd Emscripten features like split memory). * **Polyfill** WebAssembly, by running it in the interpreter compiled to JavaScript, if the browser does not yet have native support. To provide those capabilities, Binaryen has a simple and flexible API for **representing and processing** WebAssembly modules. The interpreter, validator, pretty-printer, etc. are built on that foundation. The core of this is in [wasm.h](https://github.com/WebAssembly/binaryen/blob/master/src/wasm.h), which contains classes that define a WebAssembly module, and tools to process those. For a simple example of how to use Binaryen, see [test/example/find_div0s.cpp](https://github.com/WebAssembly/binaryen/blob/master/test/example/find_div0s.cpp), which creates a module and then searches it for a specific pattern. @@ -13,9 +13,11 @@ To provide those capabilities, Binaryen has a simple and flexible API for **repr This repository contains code that builds the following tools in `bin/`: - * **binaryen-shell**: A shell that can load and interpret WebAssembly code in S-Expression format, and can run the spec test suite. - * **asm2wasm**: An asm.js-to-WebAssembly compiler, built on Emscripten's asm optimizer infrastructure. That can directly compile asm.js to WebAssembly. - * **wasm.js**: A polyfill for WebAssembly support in browsers. It receives an asm.js module, parses it using an internal build of `asm2wasm`, and runs the resulting WebAssembly in a WebAssembly interpreter. It provides what looks like an asm.js module, while running WebAssembly inside. + * **binaryen-shell**: A shell that can load and interpret WebAssembly code in S-Expression format, as well as run transformation passes on it. It can also run the spec test suite. + * **asm2wasm**: An asm.js-to-WebAssembly compiler, built on Emscripten's asm optimizer infrastructure. This is used by Emscripten in Binaryen mode when it uses Emscripten's fastcomp asm.js backend. + * **wasm2asm**: A WebAssembly-to-asm.js compiler, the reverse of `asm2wasm`. This is a work in progress. + * **s2wasm**: A compiler from the `.s` format emitted by the new WebAssembly backend being developed in LLVM. This is used by Emscripten in Binaryen mode when it integrates with the new LLVM backend. + * **wasm.js**: A WebAssembly-to-JavaScript bridge. wasm.js contains Binaryen components compiled to JavaScript, including the interpreter, `asm2wasm`, the S-Expression parser, etc., which allow you to load WebAssembly and execute it even if the browser doesn't have native support yet. Having `asm2wasm` also gives the option to take an asm.js build and execute it as WebAssembly, which is useful for testing. Usage instructions for each are below. @@ -28,6 +30,7 @@ $ ./build.sh * `binaryen-shell` and `asm2wasm` require a C++11 compiler. * If you also want to compile C/C++ to WebAssembly (and not just asm.js to WebAssembly), you'll need Emscripten. You'll need the `incoming` branch there (which you can get via [the SDK](http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html)). * `wasm.js` also requires Emscripten. +* There is work-in-progress CMake support, but it isn't stable or finished yet. ## Running @@ -119,6 +122,27 @@ For basic tests, that command should work, but in general you need a few more ar * `ALIASING_FUNCTION_POINTERS=0` because WebAssembly does not allow aliased function pointers (there is a single table). * `GLOBAL_BASE=1000` because WebAssembly lacks global variables, so `asm2wasm` maps them onto addresses in memory. This requires that you have some reserved space for those variables. With that argument, we reserve the area up to `1000`. +### C/C++ Source => WebAssembly LLVM backend => s2wasm => WebAssembly + +Binaryen's `s2wasm` tool can translate the `.s` output from the LLVM WebAssembly backend into WebAssembly. You can receive `.s` output from `llc`, and then run `s2wasm` on that: + +```` +llc code.ll -march=wasm32 -filetype=asm -o code.s +s2wasm code.s > code.wast +```` + +You can also use Emscripten, which will do those steps for you (as well as link to system libraries, etc.): + +```` +./emcc input.cpp -s WASM_BACKEND=1 -s 'BINARYEN="path-to-binaryen"' +```` + +The `WASM_BACKEND` option tells it to use the WebAssembly backend instead of the asm.js backend. + + * Due to current limitations of the WebAssembly backend, you might want to build with `-s ONLY_MY_CODE=1 -O1`, which will avoid linking in libc (which contains varargs, which are not yet supported), and optimizes so that the stack is not used (which is also not yet supported). + * The output when building in this mode is similar to what you get in general when building with Binaryen in Emscripten: a main `.js` file, and the compiled code in a `.wast` file alongside it. + * Build with `EMCC_DEBUG=1` in the env to see Emscripten's debug output as it runs the various tools, and also to save the intermediate files in `/tmp/emscripten_temp`. It will save both the `.s` and `.wast` files there (in addition to other files it normally saves). + ## Testing ``` @@ -135,19 +159,29 @@ The `check.py` script supports some options: * If an interpreter is provided, we run the output through it, checking for parse errors. * If tests are provided, we run exactly those. If none are provided, we run them all. - * `asm2wasm` tests require no dependencies. `wasm.js` tests require `emcc` and `nodejs` in the path. + * Some tests require `emcc` or `nodejs` in the path. They will not run if the tool cannot be found, and you'll see a warning. + * We have tests from upstream in `tests/spec` and `tests/experimental`, in git submodules. Running `./build.sh` should update those. (`src/emscripten-optimizer` is synced with `tools/optimizer/` in the main emscripten repo, for convenience) +## Design Principles + + * **Interned strings for names**: It's very convenient to have names on nodes, instead of just numeric indices etc. To avoid most of the performance difference between strings and numeric indices, all strings are interned, which means there is a single copy of each string in memory, string comparisons are just a pointer comparison, etc. + * **Allocate in arenas**: Based on experience with other optimizing/transformating toolchains, it's not worth the overhead to carefully track memory of individual nodes. Instead, we allocate all elements of a module in an arena, and the entire arena can be freed when the module is no longer needed. + ## FAQ * How does `asm2wasm` relate to the new WebAssembly backend which is being developed in upstream LLVM? This is separate from that. `asm2wasm` focuses on compiling asm.js to WebAssembly, as emitted by Emscripten's asm.js backend. This is useful because while in the long term Emscripten hopes to use the new WebAssembly backend, the `asm2wasm` route is a very quick and easy way to generate WebAssembly output. It will also be useful for benchmarking the new backend as it progresses. -* How about compiling asm.js to WebAssembly (the opposite direction of `asm2wasm`)? Wouldn't that be useful for polyfilling? +* How about compiling WebAssembly to asm.js (the opposite direction of `asm2wasm`)? Wouldn't that be useful for polyfilling? + +Experimentation with this is happening, in `wasm2asm`. + +This would be useful, but it is a much harder task, due to some decisions made in WebAssembly. For example, WebAssembly can have control flow nested inside expressions, which can't directly map to asm.js. It could be supported by outlining the code to another function, or to compiling it down into new basic blocks and control-flow-free instructions, but it is hard to do so in a way that is both fast to do and emits code that is fast to execute. On the other hand, compiling asm.js to WebAssembly is almost straightforward. -It would be useful, but it is a much harder task, due to some decisions made in WebAssembly. For example, WebAssembly can have control flow nested inside expressions, which can't directly map to asm.js. It could be supported by outlining the code to another function, or to compiling it down into new basic blocks and control-flow-free instructions, but it is hard to do so in a way that is both fast to do and emits code that is fast to execute. On the other hand, compiling asm.js to WebAssembly is almost straightforward. +We just have to do more work on `wasm2asm` and see how efficient we can make it. * Can `asm2wasm` compile any asm.js code? @@ -159,5 +193,5 @@ Almost. Some decisions made in WebAssembly preclude that, for example, there are "Binaryen" is a combination of **binary** - since WebAssembly is a binary format for the web - and **Emscripten** - with which it can integrate in order to compile C and C++ all the way to WebAssembly, via asm.js. Binaryen began as Emscripten's WebAssembly processing library (`wasm-emscripten`). -"Binaryen" is pronounced [in the same manner](http://www.makinggameofthrones.com/production-diary/2011/2/11/official-pronunciation-guide-for-game-of-thrones.html) as "[Targaryen](https://en.wikipedia.org/wiki/List_of_A_Song_of_Ice_and_Fire_characters#House_Targaryen)": *bi-NAIR-ee-in*. Valar Morcodeis. +"Binaryen" is pronounced [in the same manner](http://www.makinggameofthrones.com/production-diary/2011/2/11/official-pronunciation-guide-for-game-of-thrones.html) as "[Targaryen](https://en.wikipedia.org/wiki/List_of_A_Song_of_Ice_and_Fire_characters#House_Targaryen)": *bi-NAIR-ee-in*. Or something like that? Anyhow, however Targaryen is correctly pronounced, they should rhyme. Aside from pronunciation, the Targaryen house words, "Fire and Blood", have also inspired Binaryen's: "Code and Bugs." |