Home

Awesome

<h1><p align="center"><img src="https://github.com/WebAssembly/web-assembly-logo/raw/master/dist/logo/web-assembly-logo-256px.png" alt="webassembly" /><br />for node.js</p></h1>

An experimental, minimal toolkit and runtime on top of node to produce and run WebAssembly modules.

To run compiled WebAssembly modules, you'll either need a recent version of your browser with WebAssembly enabled or node.js 8 - but you probably already know that. For development, node.js 6 upwards is sufficient.

npm build status Code Climate npm downloads

Motivation

Prevalent WebAssembly tooling provides compilation to WebAssembly from a C/C++ perspective with a focus on porting existing code. Because of that, it usually produces a lot of extra code that isn't needed alongside a module that is solely trying to complement JavaScript. This package, on the other hand, tries to keep the support library and the generated modules as small as possible by specifically targeting WebAssembly (in the browser) only.

PRs welcome!

Example

Write your module as a C program:

// program.c
#include <webassembly.h>

export int add(int a, int b) {
  return a + b;
}

Compile it to wasm:

$> wa compile -o program.wasm program.c

Run it:

// program.js
require("webassembly")
  .load("program.wasm")
  .then(module => {
    console.log("1 + 2 = " + module.exports.add(1, 2));
  });

Installation

As a dependency:

$> npm install webassembly

OR to use globally with "wa compile":

$> npm install -g webassembly

Installing the package automatically downloads prebuilt binaries for either Windows (win32-x64) or Linux (linux-x64).

Toolkit

WebAssembly functionality is provided by a C header. A small JavaScript support library (distributions) provides the browser runtime.

Calling webassembly.load(file: string, [options: LoadOptions]): Promise<IModule> returns a promise for a module instance:

Available LoadOptions:

C features available out of the box:

Console functions accept the following string substitutions with variable arguments:

Subst.C typeDescription
%d, %iint / int32_tSigned 32 bit integer
%uunsigned int / uint32_tUnsigned 32 bit integer
%ffloat32 bit float
%lfdouble64 bit double
%schar *String (zero terminated)

Browser Math (i.e. Math_sqrt) as well as standard C math.h can be used.

On the JS side of things, the memory instance (module.memory) has additional mixed in utility methods for convenient memory access:

The underlying typed array views are also available for direct use. Just make sure to access them directly on the memory instance because they are updated when the program memory grows.

Command line

The wa-compile utility (also callable as wa compile, wa comp, wa c) compiles C code to a WebAssembly module.

  -o, --out        Specifies the .wasm output file. Defaults to stdout.
  -d, --debug      Prints debug information to stderr.
  -q, --quiet      Suppresses informatory output.

  Module configuration:

  -O, --optimize   Optimizes the output file and removes dead code.
  -s, --stack      Specifies the stack size. Defaults to 10000.
  -m, --main       Executes the specified function on load.
  -D, --define     Defines a macro.

  Includes and libraries:

  -I, --headers    Includes C headers from the specified directories.
  -i, --include    Includes the specified source files.
  -l, --link       Links in the specified libraries after compilation.
  -b, --bare       Does not include the runtime library.

usage: wa-compile [options] program.c

The wa-link utility (also callable as wa link, wa ln, wa l) linkes multiple WebAssembly modules to one.

  -o, --out      Specifies the .wasm output file. Defaults to write to stdout.
  -d, --debug    Prints debug information to stderr.
  -q, --quiet    Suppresses informatory output.

  Module configuration:

  -O, --optimize   Performs link-time optimizations.

usage: wa-link [options] program1.wasm program2.wasm

The wa-disassemble utility (also callable as wa disassemble, wa dis, wa d) decompiles a WebAssembly module to text format.

  -o, --out      Specifies the .wast output file. Defaults to stdout.
  -d, --debug    Prints debug information to stderr.
  -q, --quiet    Suppresses informatory output.

usage: wa-disassemble [options] program.wasm

The wa-assemble utility (also callable as wa assemble, wa as, wa a) assembles WebAssembly text format to a module.

  -o, --out        Specifies the .wasm output file. Defaults to stdout.
  -d, --debug      Prints debug information to stderr.
  -q, --quiet      Suppresses informatory output.

  Module configuration:

  -O, --optimize   Optimizes the output file and removes dead code.

usage: wa-assemble [options] program.wast

The wa utility proxies to the above, in case you don't like typing -.

Command line utilites can also be used programmatically by providing command line arguments and a callback to their respective main functions:

var compiler = require("webassembly/cli/compiler");
               // or assembler, disassembler, linker
compiler.main([
  "-o", "program.wasm",
  "program.c"
], function(err, filename) {
  if (err)
    throw err;
  console.log("saved to: " + filename);
});

IDE integration

Anything should work as long as you are able to configure it, even notepad.

I am using:


License: MIT License.

Includes parts of

WebAssembly logo by Carlos Baraza (CC0 1.0 Universal).