binaryen

Build Status Windows CI

Binaryen

Binaryen is a compiler and toolchain infrastructure library for WebAssembly, written in C++. It aims to make compiling to WebAssembly easy, fast, and effective:

Compilers built using Binaryen include

Binaryen also provides a set of toolchain utilities that can

Consult the contributing instructions if you’re interested in participating.

Binaryen IR

Binaryen’s internal IR is designed to be

There are a few differences between Binaryen IR and the WebAssembly language:

As a result, you might notice that round-trip conversions (wasm => Binaryen IR => wasm) change code a little in some corner cases.

Notes when working with Binaryen IR:

Tools

This repository contains code that builds the following tools in bin/:

Usage instructions for each are below.

Building

cmake . && make

Note that you can also use ninja as your generator: cmake -G Ninja . && ninja

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.

Visual C++

  1. Using the Microsoft Visual Studio Installer, install the “Visual C++ tools for CMake” component.

  2. 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”.

  3. 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.

Running

wasm-opt

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.wat --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.wat --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:

wasm2js

Run

bin/wasm2js [input.wasm file]

This will print out JavaScript to the console.

For example, try

$ bin/wasm2js test/hello_world.wat

That output contains

 function add(x, y) {
  x = x | 0;
  y = y | 0;
  return x + y | 0 | 0;
 }

as a translation of

 (func $add (; 0 ;) (type $0) (param $x i32) (param $y i32) (result i32)
  (i32.add
   (local.get $x)
   (local.get $y)
  )
 )

wasm2js’s output is in ES6 module format - basically, it converts a wasm module into an ES6 module (to run on older browsers and Node.js versions you can use Babel etc. to convert it to ES5). Let’s look at a full example of calling that hello world wat; first, create the main JS file:

// main.mjs
import { add } from "./hello_world.mjs";
console.log('the sum of 1 and 2 is:', add(1, 2));

The run this (note that you need a new enough Node.js with ES6 module support):

$ bin/wasm2js test/hello_world.wat -o hello_world.mjs
$ node --experimental-modules main.mjs
the sum of 1 and 2 is: 3

Things keep to in mind with wasm2js’s output:

asm2wasm

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:

example output

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.

C/C++ Source ⇒ asm2wasm ⇒ WebAssembly

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.

Testing

./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]..

Design Principles

FAQ

“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.