Skip to content
The WebAssembly Binary Toolkit
C++ Python C CMake JavaScript Shell Other
Branch: master
Clone or download

Latest commit

binji Convert Type from an enum into a class (#1350)
This is similar to the way Opcode is structured, which allows us to hang
member functions off of the enumeration.

The primary motivator for this change is the GC proposal (and the
function-references proposal) where a Type can be parameterized:

     (type $T (struct ...))
     (func
       (local (ref $T)
       ...
     )

In this case the type is ref, with a parameter of the type index. Making
Type a class will make it easier to store this additional information.
Latest commit f8e09f6 Feb 29, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows actions: Avoid triggering both branch and pr builds (#1329) Feb 7, 2020
cmake Rewrite the lexer manually, instead of re2c (#1058) Apr 4, 2019
docs wasm-decompile: use symbols from linking section for names. (#1318) Jan 27, 2020
fuzz-in Update testsuite (#1275) Jan 9, 2020
man Put rendered man page html in docs, not .1 files Jan 18, 2020
scripts Remove support for python2 (#1321) Jan 31, 2020
src Convert Type from an enum into a class (#1350) Feb 29, 2020
test Update testsuite (w/ reference-types changes) (#1351) Feb 29, 2020
third_party Update testsuite (w/ reference-types changes) (#1351) Feb 29, 2020
wasm2c [wasm2c] Fix realloc check in wasm_rt_grow_memory (#1171) Sep 25, 2019
.appveyor.yml [appveyor] Add script to allow RDP into CI bots (#1334) Feb 20, 2020
.clang-format add .clang-format Sep 16, 2015
.flake8 Switch python indentation from 2-space to 4-space (#1145) Aug 15, 2019
.gitattributes Move documentation to docs/ directory Jan 18, 2020
.gitignore Fix up CMake warning (#1081) May 17, 2019
.gitmodules Initial WASM C API implementation. (#1250) Jan 16, 2020
.style.yapf Add support for yapf python formatting tool (#276) Jan 18, 2017
.travis.yml [travis] Switch to xenial (#1324) Jan 31, 2020
CMakeLists.txt Share validator between IR + binary-reader-interp (#1346) Feb 27, 2020
Contributing.md update Contributing to point to README.md Sep 6, 2016
LICENSE Revert appendix to original form (#848) May 29, 2018
Makefile Move documentation to docs/ directory Jan 18, 2020
README.md wasm-decompile: documentation. (#1295) Jan 10, 2020
ubsan.blacklist Fix ubsan build and remove workaround in favor of ubsan.blacklist (#678) Nov 29, 2017

README.md

Github CI Status Build Status Windows status

WABT: The WebAssembly Binary Toolkit

WABT (we pronounce it "wabbit") is a suite of tools for WebAssembly, including:

  • wat2wasm: translate from WebAssembly text format to the WebAssembly binary format
  • wasm2wat: the inverse of wat2wasm, translate from the binary format back to the text format (also known as a .wat)
  • wasm-objdump: print information about a wasm binary. Similiar to objdump.
  • wasm-interp: decode and run a WebAssembly binary file using a stack-based interpreter
  • wasm-decompile: decompile a wasm binary into readable C-like syntax.
  • wat-desugar: parse .wat text form as supported by the spec interpreter (s-expressions, flat syntax, or mixed) and print "canonical" flat format
  • wasm2c: convert a WebAssembly binary file to a C source and header
  • wasm-strip: remove sections of a WebAssembly binary file
  • wasm-validate: validate a file in the WebAssembly binary format
  • wast2json: convert a file in the wasm spec test format to a JSON file and associated wasm binary files
  • wasm-opcodecnt: count opcode usage for instructions
  • spectest-interp: read a Spectest JSON file, and run its tests in the interpreter

These tools are intended for use in (or for development of) toolchains or other systems that want to manipulate WebAssembly files. Unlike the WebAssembly spec interpreter (which is written to be as simple, declarative and "speccy" as possible), they are written in C/C++ and designed for easier integration into other systems. Unlike Binaryen these tools do not aim to provide an optimization platform or a higher-level compiler target; instead they aim for full fidelity and compliance with the spec (e.g. 1:1 round-trips with no changes to instructions).

Online Demos

Wabt has been compiled to JavaScript via emscripten. Some of the functionality is available in the following demos:

Supported Proposals

  • Proposal: Name and link to the WebAssembly proposal repo
  • flag: Flag to pass to the tool to enable support for the feature
  • binary: Whether wabt can read/write the binary format
  • text: Whether wabt can read/write the text format
  • validate: Whether wabt can validate the syntax
  • interpret: Whether wabt can execute these operations in wasm-interp or spectest-interp
Proposal flag binary text validate interpret
exception handling --enable-exceptions
mutable globals --disable-mutable-globals
nontrapping float-to-int conversions --enable-saturating-float-to-int
sign extension --enable-sign-extension
simd --enable-simd
threads --enable-threads
multi-value --enable-multi-value
tail-call --enable-tail-call
bulk memory --enable-bulk-memory
reference types --enable-reference-types
annotations --enable-annotations

Cloning

Clone as normal, but don't forget to get the submodules as well:

$ git clone --recursive https://github.com/WebAssembly/wabt
$ cd wabt

This will fetch the testsuite and gtest repos, which are needed for some tests.

Building using CMake directly (Linux and macOS)

You'll need CMake. You can then run CMake, the normal way:

$ mkdir build
$ cd build
$ cmake ..
$ cmake --build .

This will produce build files using CMake's default build generator. Read the CMake documentation for more information.

NOTE: You must create a separate directory for the build artifacts (e.g. build above). Running cmake from the repo root directory will not work since the build produces an executable called wasm2c which conflicts with the wasm2c directory.

Building using the top-level Makefile (Linux and macOS)

NOTE: Under the hood, this uses make to run CMake, which then calls make again. On some systems (typically macOS), this doesn't build properly. If you see these errors, you can build using CMake directly as described above.

You'll need CMake. If you just run make, it will run CMake for you, and put the result in bin/clang/Debug/ by default:

Note: If you are on macOS, you will need to use CMake version 3.2 or higher

$ make

This will build the default version of the tools: a debug build using the Clang compiler.

There are many make targets available for other configurations as well. They are generated from every combination of a compiler, build type and configuration.

  • compilers: gcc, clang, gcc-i686, gcc-fuzz
  • build types: debug, release
  • configurations: empty, asan, msan, lsan, ubsan, no-tests

They are combined with dashes, for example:

$ make clang-debug
$ make gcc-i686-release
$ make clang-debug-lsan
$ make gcc-debug-no-tests

Building (Windows)

You'll need CMake. You'll also need Visual Studio (2015 or newer) or MinGW.

Note: Visual Studio 2017 and later come with CMake (and the Ninja build system) out of the box, and should be on your PATH if you open a Developer Command prompt. See https://aka.ms/cmake for more details.

You can run CMake from the command prompt, or use the CMake GUI tool. See Running CMake for more information.

When running from the commandline, create a new directory for the build artifacts, then run cmake from this directory:

> cd [build dir]
> cmake [wabt project root] -DCMAKE_BUILD_TYPE=[config] -DCMAKE_INSTALL_PREFIX=[install directory] -G [generator]

The [config] parameter should be a CMake build type, typically DEBUG or RELEASE.

The [generator] parameter should be the type of project you want to generate, for example "Visual Studio 14 2015". You can see the list of available generators by running cmake --help.

To build the project, you can use Visual Studio, or you can tell CMake to do it:

> cmake --build [wabt project root] --config [config] --target install

This will build and install to the installation directory you provided above.

So, for example, if you want to build the debug configuration on Visual Studio 2015:

> mkdir build
> cd build
> cmake .. -DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_INSTALL_PREFIX=..\ -G "Visual Studio 14 2015"
> cmake --build . --config DEBUG --target install

Adding new keywords to the lexer

If you want to add new keywords, you'll need to install gperf. Before you upload your PR, please run make update-gperf to update the prebuilt C++ sources in src/prebuilt/.

Running wat2wasm and wast2json

Some examples:

# parse and typecheck test.wat
$ bin/wat2wasm test.wat

# parse test.wat and write to binary file test.wasm
$ bin/wat2wasm test.wat -o test.wasm

# parse spec-test.wast, and write verbose output to stdout (including the
# meaning of every byte)
$ bin/wat2wasm spec-test.wast -v

# parse spec-test.wast, and write files to spec-test.json. Modules are written
# to spec-test.0.wasm, spec-test.1.wasm, etc.
$ bin/wast2json spec-test.wast -o spec-test.json

You can use --help to get additional help:

$ bin/wat2wasm --help

Or try the online demo.

Running wasm2wat

Some examples:

# parse binary file test.wasm and write text file test.wat
$ bin/wasm2wat test.wasm -o test.wat

# parse test.wasm and write test.wat
$ bin/wasm2wat test.wasm -o test.wat

You can use --help to get additional help:

$ bin/wasm2wat --help

Or try the online demo.

Running wasm-interp

Some examples:

# parse binary file test.wasm, and type-check it
$ bin/wasm-interp test.wasm

# parse test.wasm and run all its exported functions
$ bin/wasm-interp test.wasm --run-all-exports

# parse test.wasm, run the exported functions and trace the output
$ bin/wasm-interp test.wasm --run-all-exports --trace

# parse test.json and run the spec tests
$ bin/wasm-interp test.json --spec

# parse test.wasm and run all its exported functions, setting the value stack
# size to 100 elements
$ bin/wasm-interp test.wasm -V 100 --run-all-exports

You can use --help to get additional help:

$ bin/wasm-interp --help

Running wasm-decompile

For example:

# parse binary file test.wasm and write text file test.dcmp
$ bin/wasm-decompile test.wasm -o test.dcmp

You can use --help to get additional help:

$ bin/wasm-decompile --help

See decompiler.md for more information on the language being generated.

Running wasm2c

See wasm2c.md

Running the test suite

See test/README.md.

Sanitizers

To build with the LLVM sanitizers, append the sanitizer name to the target:

$ make clang-debug-asan
$ make clang-debug-msan
$ make clang-debug-lsan
$ make clang-debug-ubsan

There are configurations for the Address Sanitizer (ASAN), Memory Sanitizer (MSAN), Leak Sanitizer (LSAN) and Undefine Behavior Sanitizer (UBSAN). You can read about the behaviors of the sanitizers in the link above, but essentially the Address Sanitizer finds invalid memory accesses (use after free, access out-of-bounds, etc.), Memory Sanitizer finds uses of uninitialized memory, the Leak Sanitizer finds memory leaks, and the Undefined Behavior Sanitizer finds undefined behavior (surprise!).

Typically, you'll just want to run all the tests for a given sanitizer:

$ make test-asan

You can also run the tests for a release build:

$ make test-clang-release-asan
...

The Travis bots run all of these tests (and more). Before you land a change, you should run them too. One easy way is to use the test-everything target:

$ make test-everything

To run everything the Travis bots do, you can use the following scripts:

$ CC=gcc scripts/travis-build.sh
$ CC=gcc scripts/travis-test.sh
$ CC=clang scripts/travis-build.sh
$ CC=clang scripts/travis-test.sh
You can’t perform that action at this time.