commit | ddb5acd34238967a2487a70926849c89f38a35e2 | [log] [tgz] |
---|---|---|
author | Alon Zakai <alonzakai@gmail.com> | Thu Jan 31 17:35:32 2019 |
committer | GitHub <noreply@github.com> | Thu Jan 31 17:35:32 2019 |
tree | 35be190a17fc8b1d9a0824dd5a4376f46d53c9a0 | |
parent | 5f1afa58d22dce1088c63eff690283d8c615feee [diff] |
Strip the producers section in --strip-producers (#1875) WebAssembly/tool-conventions#93 has a summary of emscripten's current thinking on this. For Binaryen, we don't want to do anything to the producers section by default, but do want it to be possible to optionally remove it. To achieve that, this PR * creates a --strip-producers pass that removes that section. * creates a --strip-debug pass that removes debug info, same as the old --strip, which is still around but deprecated. A followup in emscripten will use this pass by default.
Binaryen is a compiler and toolchain infrastructure library for WebAssembly, written in C++. It aims to make compiling to WebAssembly easy, fast, and effective:
Easy: Binaryen has a simple C API in a single header, and can also be used from JavaScript. It accepts input in WebAssembly-like form but also accepts a general control flow graph for compilers that prefer that.
Fast: Binaryen‘s internal IR uses compact data structures and is designed for completely parallel codegen and optimization, using all available CPU cores. Binaryen’s IR also compiles down to WebAssembly extremely easily and quickly because it is essentially a subset of WebAssembly.
Effective: Binaryen's optimizer has many passes that can improve code very significantly (e.g. local coloring to coalesce local variables; dead code elimination; precomputing expressions when possible at compile time; etc.). These optimizations aim to make Binaryen powerful enough to be used as a compiler backend by itself. One specific area of focus is on WebAssembly-specific optimizations (that general-purpose compilers might not do), which you can think of as wasm minification , similar to minification for JavaScript, CSS, etc., all of which are language-specific (an example of such an optimization is block return value generation in SimplifyLocals
).
Compilers built using Binaryen include
asm2wasm
which compiles asm.js to WebAssemblyAssemblyScript
which compiles TypeScript to Binaryen IRwasm2js
which compiles WebAssembly to JSAsterius
which compiles Haskell to WebAssemblyBinaryen also provides a set of toolchain utilities that can
Consult the contributing instructions if you're interested in participating.
Binaryen's internal IR is designed to be
There are a few differences between Binaryen IR and the WebAssembly language:
--generate-stack-ir --print-stack-ir
, which prints Stack IR, this is guaranteed to be valid for wasm parsers.)As a result, you might notice that round-trip conversions (wasm => Binaryen IR => wasm) change code a little in some corner cases.
src/wasm-stack.h
). Stack IR allows a bunch of optimizations that are tailored for the stack machine form of WebAssembly‘s binary format (but Stack IR is less efficient for general optimizations than the main Binaryen IR). If you have a wasm file that has been particularly well-optimized, a simple round-trip conversion (just read and write, without optimization) may cause more noticeable differences, as Binaryen fits it into Binaryen IR’s more structured format. If you also optimize during the round-trip conversion then Stack IR opts will be run and the final wasm will be better optimized.Notes when working with Binaryen IR:
This repository contains code that builds the following tools in bin/
:
Usage instructions for each are below.
cmake . && make
Note that you can also use ninja
as your generator: cmake -G Ninja . && ninja
build-js.sh
, see notes inside. Normally this is not needed as builds are provided in this repo already.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), for more details see the wiki.
Using the Microsoft Visual Studio Installer, install the “Visual C++ tools for CMake” component.
Generate the projects:
mkdir build cd build "%VISUAL_STUDIO_ROOT%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe" ..
Substitute VISUAL_STUDIO_ROOT with the path to your Visual Studio installation. In case you are using the Visual Studio Build Tools, the path will be “C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools”.
From the Developer Command Prompt, build the desired projects:
msbuild binaryen.vcxproj
CMake generates a project named “ALL_BUILD.vcxproj” for conveniently building all the projects.
Run
bin/wasm-opt [.wasm or .wat file] [options] [passes, see --help] [--help]
The wasm optimizer receives WebAssembly as input, and can run transformation passes on it, as well as print it (before and/or after the transformations). For example, try
bin/wasm-opt test/passes/lower-if-else.wast --print
That will pretty-print out one of the test cases in the test suite. To run a transformation pass on it, try
bin/wasm-opt test/passes/lower-if-else.wast --print --lower-if-else
The lower-if-else
pass lowers if-else into a block and a break. You can see the change the transformation causes by comparing the output of the two print commands.
It's easy to add your own transformation passes to the shell, just add .cpp
files into src/passes
, and rebuild the shell. For example code, take a look at the lower-if-else
pass.
Some more notes:
bin/wasm-opt --help
for the full list of options and passes.--debug
will emit some debugging info.run
bin/asm2wasm [input.asm.js file]
This will print out a WebAssembly module in s-expression format to the console.
For example, try
$ bin/asm2wasm test/hello_world.asm.js
That input file contains
function () { "use asm"; function add(x, y) { x = x | 0; y = y | 0; return x + y | 0; } return { add: add }; }
You should see something like this:
By default you should see pretty colors as in that image. Set COLORS=0
in the env to disable colors if you prefer that. On Linux and Mac, you can set COLORS=1
in the env to force colors (useful when piping to more
, for example). For Windows, pretty colors are only available when stdout/stderr
are not redirected/piped.
Pass --debug
on the command line to see debug info, about asm.js functions as they are parsed, etc.
When using emcc
with the BINARYEN
option, it will use Binaryen to build to WebAssembly. This lets you compile C and C++ to WebAssembly, with emscripten using asm.js internally as a build step. Since emscripten's asm.js generation is very stable, and asm2wasm is a fairly simple process, this method of compiling C and C++ to WebAssembly is usable already. See the emscripten wiki for more details about how to use it.
./check.py
(or python check.py
) will run wasm-shell
, wasm-opt
, asm2wasm
, etc. on the testcases in test/
, and verify their outputs.
The check.py
script supports some options:
./check.py [--interpreter=/path/to/interpreter] [TEST1] [TEST2]..
emcc
or nodejs
in the path. They will not run if the tool cannot be found, and you'll see a warning.tests/spec
, in git submodules. Running ./check.py
should update those.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.
asm2wasm
)? Wouldn't that be useful for polyfilling?Experimentation with this is happening, in wasm2js
.
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.
We just have to do more work on wasm2js
and see how efficient we can make it.
asm2wasm
compile any asm.js code?Almost. Some decisions made in WebAssembly preclude that, for example, there are no global variables. That means that asm2wasm
has to map asm.js global variables onto locations in memory, but then it must know of a safe zone in memory in which to do so, and that information is not directly available in asm.js.
asm2wasm
do some integration with Emscripten in order to work around these issues, like asking Emscripten to reserve same space for the globals, etc.
“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 as “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.”
Yes, it does. Here's a step-by-step tutorial on how to compile it under Windows 10 x64 with with CMake and Visual Studio 2015. Help would be appreciated on Windows and OS X as most of the core devs are on Linux.